{"id":13571318,"url":"https://github.com/artagnon/clayoven","last_synced_at":"2025-10-23T19:37:46.152Z","repository":{"id":6908917,"uuid":"8159296","full_name":"artagnon/clayoven","owner":"artagnon","description":"💎 beautiful website generator aimed at math-heavy sites","archived":false,"fork":false,"pushed_at":"2024-08-23T18:12:05.000Z","size":36202,"stargazers_count":331,"open_issues_count":0,"forks_count":7,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-03T23:12:05.551Z","etag":null,"topics":["ruby","static-site-generator"],"latest_commit_sha":null,"homepage":"http://artagnon.github.io/clayoven/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artagnon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-02-12T13:33:49.000Z","updated_at":"2024-12-20T18:23:51.000Z","dependencies_parsed_at":"2024-01-13T20:13:17.697Z","dependency_job_id":"d790bb0d-cb30-4c94-a8dd-537f36f2e215","html_url":"https://github.com/artagnon/clayoven","commit_stats":{"total_commits":389,"total_committers":3,"mean_commits":"129.66666666666666","dds":"0.028277634961439535","last_synced_commit":"5abfe57c740a0c7868772ba2e4609b0585044d94"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artagnon%2Fclayoven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artagnon%2Fclayoven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artagnon%2Fclayoven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artagnon%2Fclayoven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artagnon","download_url":"https://codeload.github.com/artagnon/clayoven/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248631696,"owners_count":21136559,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ruby","static-site-generator"],"created_at":"2024-08-01T14:01:00.980Z","updated_at":"2025-10-23T19:37:41.132Z","avatar_url":"https://github.com/artagnon.png","language":"Ruby","funding_links":[],"categories":["Ruby"],"sub_categories":[],"readme":"# clayoven ![logo](assets/clayoven.png)\n\n[![Maintainability](https://img.shields.io/codeclimate/maintainability/artagnon/clayoven?style=for-the-badge\u0026logo=code-climate\u0026labelColor=000000\u0026label=Maintainability)](https://codeclimate.com/github/artagnon/clayoven/maintainability)\n[![Test Coverage](https://img.shields.io/codeclimate/coverage/artagnon/clayoven?style=for-the-badge\u0026logo=code-climate\u0026labelColor=000000\u0026label=Test%20Coverage)](https://codeclimate.com/github/artagnon/clayoven/test_coverage)\n\nclayoven is a beautiful static site generator with a carefully curated set of features. It has been built at a glacial pace, over a period of [nine years](https://github.com/artagnon/clayoven/commit/d4d40161e9f76dbe74078c669de9af698cf621d6), as [my website](https://artagnon.com) expanded in content. I have a spread of mathematical notes, both typeset and handwritten, software-related posts, and some wider-audience articles; while clayoven is primarily aimed at math-heavy sites, it is good on all three fronts. The source files are written in \"claytext\", a custom format built for elegance and speed.\n\nrdoc documentation is available [here](http://artagnon.github.io/clayoven/).\n\n## Unique features\n\n- Small! ~700 lines of well-written and well-documented Ruby.\n- Beautiful and easily extensible markup, with a dedicated vscode plugin for it.\n- Automatically picks timestamps from git history, respecting moves.\n- Server-side rendering of math, including commutative diagrams, via MathJaX and XyJaX.\n\n## Demo\n\nA starter project is bundled with the following `scratch.index.clay`:\n\n![syntax highlighting demo](https://user-images.githubusercontent.com/37226/113478818-91a7f280-948b-11eb-87f0-3610f2aa3160.png)\n\nwhose rendered output can be seen [here](https://artagnon.com/scratch).\n\nHere's an excerpt of embedded MathJaX with IntelliSense powered by vsclay:\n\n![IntelliSense demo](https://user-images.githubusercontent.com/37226/113474233-24866400-946f-11eb-8e72-b82460d16c71.mp4)\n\n## Getting started\n\nThere is no published gem. To get started, clone, run `bundle` to install the required gems, and put `bin/clayoven` in `$PATH`. Then, run `clayoven init` in a fresh directory. To start writing, install [vsclay](https://marketplace.visualstudio.com/items?itemName=artagnon.vsclay) for vscode, which will provide the necessary syntax highlighting, IntelliSense support for MathJaX, and trigger-[incremental build]-on-save functionality.\n\n## The site-generation engine\n\nAll site content is split up into \"topics\", to put in the sidebar, each of which can either serve as an index to a collection of `ContentPages` (as a bunch of `.clay` files in a subdirectory with the name `#{topic}`), or a single `IndexPage` (named `#{topic}.index.clay`). `index.clay` is special-cased to serve as the root of the site.\n\nSo, if you have these files,\n\n    .vscode/                # provided by `init`\n    .htaccess               # provided by `init`\n    lib/                    # provided by `init`\n    design/                 # provided by `init`\n    index.clay              # provided by `init`\n    scratch.index.clay      # provided by `init`\n    404.index.clay          # provided by `init`\n    blog.index.clay\n    blog/personal/1.clay\n    blog/math/1.clay\n    colophon.index.clay\n\nclayoven automatically builds a sidebar with `index`, `blog` and `colophon` (each of which are instances of `IndexPage`). `/blog` will have links to the posts `/blog/personal/1` and `/blog/math/1` (each of which are instances of `ContentPage`), under the titles `personal` and `math` (the \"subtopics\"). If there are multiple `ContentPage` entries under an `IndexPage`, the latter simply serves to give a introduction, with links to articles automatically appearing after the introduction. `IndexPage` and `ContentPage` are run through the same `design/template.slim`, and the template file has access to the accessors.\n\nThe engine works closely with the git object store, and builds are incremental by default; it mostly Just Works, and when it doesn't, there's an option to force a full rebuild. The engine also pulls out the created-timestamp (`Page#crdate`) and last-modified-timestamp (`Page#lastmod`) from git, respecting moves. `ContentPages` are sorted by `crdate`, reverse-chronologically, and `IndexPages` are sorted alphabetically.\n\n## Usage\n\n- `clayoven init` to generate the necessary starter project.\n- `clayoven` to generate HTML files incrementally based on the current git index.\n- `clayoven aggressive` to regenerate the entire site; only requires to be run on occassion.\n- `clayoven httpd` to preview your website locally.\n\n## Configuration\n\n1. `.clayoven/sitename` is URL of the site, excluding the `https://` prefix.\n2. `.clayoven/hidden` is a list of `IndexFiles` that should be built, but not displayed in the sidebar. You would want to use it for your 404 page and drafts.\n3. `.clayoven/tz` is a timezone-to-location mapper, with lines of the form `+0000 London`. clayoven digs through the git history for locations, and exposes a `Page#locations`.\n4. `.clayoven/subtopic` is a [subtopic directory]-to-subtitle mapper, with lines of the form `inf ∞-categories`.\n\n## The claytext processor\n\nThe claytext processor is, at its core, a paragraph-processor; all content must be split up into either plain paragraphs, or \"fences\" (multiple paragraphs delimited by start and end tokens). The function of most markers should be evident from the `scratch.html` produced by a `clayoven init`. The format is strict, and the processor doesn't like files with paragraphs wrapped using hard line breaks.\n\n`Clayoven::Claytext::Transforms::LINE` matches paragraphs where all lines begin with some regex, and `Clayoven::Claytext::Transforms::Fenced` match fences (could be multiple paragraphs) that start and end with the specified tokens. In addition to this, there are inline markdown markers `` `...` `` and `[...](...)`, for content that is to be put in `\u003cmark\u003e` and `\u003ca\u003e`, respectively.\n\n## Tips\n\n- Check in the generated HTML to the site's repository, so that eyeballing `git diff` can serve as a testing mechanism.\n- If you accidentally commit `.clay` files before running clayoven, running it afterward will do nothing, since it will see a clean git index; you'll need to run the aggressive variant.\n- Importing historical content is easy; a `git commit --date=\"#{historical_date}\"` would give the post an appropriate creation date that will be respected in the sorting-order.\n\n## Planned features, and anti-features\n\n- Have one unified dhall configuration.\n- Allow the user to extend claytext syntax with configuration.\n- Hit 100% test coverage.\n- Get vsclay to report syntax errors.\n- Anti: extend clayoven in ways that would necessitate an ugly implementation.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartagnon%2Fclayoven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartagnon%2Fclayoven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartagnon%2Fclayoven/lists"}