# yuanme

> A static site generator for programmers' and mathematicians' sites, in Markdown and Org, built to be driven by coding agents.

These docs are for yuanme's main branch, which may be ahead of the latest release.
A project's own docs, for the yuanme it uses, are in its `.yuanme/docs/` folder, and `yuanme docs` prints them.

## Getting started

- [Getting started](https://docs.eyuan.me/docs/getting-started/): Install yuanme, make a Site with one Post, check it and build it.
- [Deploying](https://docs.eyuan.me/docs/deploying/): What yuanme build writes, the Host adapter for each static host, the cache policy, headers, redirects and the 404 Page.

## Guides

- [Collections and fields](https://docs.eyuan.me/docs/collections/): Collections and their Entries, the fields every Entry has and the ones a Collection declares, Slugs, Taxonomies, Data files, and yuanme new.
- [Markdown](https://docs.eyuan.me/docs/markdown/): The Markdown yuanme reads: CommonMark with GFM, heading ids and Labels, links between Entries, raw HTML, code blocks and ::: blocks.
- [The Org subset](https://docs.eyuan.me/docs/org/): How an Org file becomes an Entry, which Org yuanme renders, what it rejects or warns about, and where it differs from Emacs.
- [Math and Theorem blocks](https://docs.eyuan.me/docs/math/): LaTeX math in Markdown and Org, rendered to MathML at build time, with numbered equations, Labels, references and macros.
- [Templates](https://docs.eyuan.me/docs/templates/): The Jinja files that make each Page, what each kind of Route sees, the filters yuanme adds, Layouts and Partials, and what check finds in them.
- [Components](https://docs.eyuan.me/docs/components/): Reusable pieces of Templates with declared props, how to call them, how they differ from Partials, and the Sidecars beside them.
- [Styles](https://docs.eyuan.me/docs/styles/): Link stylesheets from a Template; yuanme bundles their imports, runs Tailwind for one that imports it, adds prefixes for your browsers, minifies and hashes them, and copies Static files as they are.
- [Scripts](https://docs.eyuan.me/docs/scripts/): Load TypeScript or JavaScript modules from a Template; yuanme bundles them, with packages from node_modules, into minified and hashed chunks.
- [Images](https://docs.eyuan.me/docs/images/): How Entry bodies name images, what yuanme makes of them, the image field type, and the [images] settings.
- [Budgets](https://docs.eyuan.me/docs/budgets/): The Site budgets yuanme build measures every Page against, how to change them, strict mode, and the build report.

## Reference

- [Site config](https://docs.eyuan.me/docs/config/): yuanme.toml, the one file that declares the Site, with every key it takes.
- [The CLI](https://docs.eyuan.me/docs/cli/): Every command and flag, the exit codes, and the JSON that --json prints.

## Diagnostic codes

- [asset/ambiguous-url](https://docs.eyuan.me/codes/asset/ambiguous-url/): A URL names both a project file, which yuanme processes and hashes, and a Static file, which it copies unchanged: `/styles/site.css` is both `styles/site.css` and `static/styles/site.css`.
- [asset/classic-script](https://docs.eyuan.me/codes/asset/classic-script/): A `<script src>` without `type="module"` names a project file.
- [asset/css-in-script](https://docs.eyuan.me/codes/asset/css-in-script/): A Script imports a stylesheet.
- [asset/dependencies-not-installed](https://docs.eyuan.me/codes/asset/dependencies-not-installed/): A Script or stylesheet imports a package, and the project has a `package.json` but no `node_modules`.
- [asset/invalid-css](https://docs.eyuan.me/codes/asset/invalid-css/): A stylesheet can't be bundled: it isn't valid CSS or UTF-8, or it imports one file twice in ways that can't be merged, such as under two different `@layer`s.
- [asset/invalid-script](https://docs.eyuan.me/codes/asset/invalid-script/): A Script can't be bundled: it isn't valid JavaScript or TypeScript, or isn't UTF-8, or it imports a name the other module doesn't export, or a `<script type="module">` names a file that is no Script.
- [asset/jsx](https://docs.eyuan.me/codes/asset/jsx/): A Script is a `.jsx` or `.tsx` file, or has JSX in it.
- [asset/not-found](https://docs.eyuan.me/codes/asset/not-found/): A `<link href>` or `<script src>` in a Page, an `@import` or `url()` in a stylesheet, or an `import` in a Script names a path that is no file of the project, no Static file and no URL of the Site.
- [asset/scope-collision](https://docs.eyuan.me/codes/asset/scope-collision/): Two Sidecar stylesheets have the same scope attribute, which yuanme makes from each one's path, so each one's styles would reach the other's Template.
- [asset/script-warning](https://docs.eyuan.me/codes/asset/script-warning/): The bundler warns about a Script, or a package it imports, that works but is likely a mistake, such as calling `eval` or importing a name that is always `undefined`.
- [asset/tailwind-error](https://docs.eyuan.me/codes/asset/tailwind-error/): Tailwind can't build a stylesheet that does `@import "tailwindcss"`: the Tailwind CLI reports an error, such as an `@apply` of a utility that doesn't exist or an `@plugin` it can't find, or a stylesheet that another one imports, or a Sidecar, imports Tailwind.
- [asset/tool-unavailable](https://docs.eyuan.me/codes/asset/tool-unavailable/): yuanme can't get a Managed tool the Site needs, such as the Tailwind CLI for a stylesheet that imports Tailwind, or TypeScript's `tsc` with `[typescript] check = true`.
- [asset/type-error](https://docs.eyuan.me/codes/asset/type-error/): With `[typescript] check = true`, TypeScript's `tsc` finds a type error in a Script, or in a file a Script imports.
- [asset/unmatched-selector](https://docs.eyuan.me/codes/asset/unmatched-selector/): A selector in a Sidecar stylesheet can match no tag its own Template writes.
- [budget/css](https://docs.eyuan.me/codes/budget/css/): The CSS a Page loads is over its Site budget, `budgets.css`: its stylesheets and `<style>` elements, each in kB of Brotli at quality 11.
- [budget/fonts](https://docs.eyuan.me/codes/budget/fonts/): The text fonts a Page loads are over their Site budget, `budgets.fonts`: every font file that a stylesheet the Page loads names in `url()`, or that the Page preloads, but the math font, in kB of Brotli at quality 11.
- [budget/html](https://docs.eyuan.me/codes/budget/html/): A Page's first-flight HTML is over its Site budget, `budgets.html`: the whole document in kB of Brotli at quality 11, but an Entry's Page without its body, which the build report lists apart.
- [budget/js](https://docs.eyuan.me/codes/budget/js/): The JS a Page runs as it loads is over its Site budget, `budgets.js`: its Scripts, the chunks they import and its inline `<script>`s, each in kB of Brotli at quality 11.
- [budget/math-font](https://docs.eyuan.me/codes/budget/math-font/): The math font a Page that shows math loads is over its Site budget, `budgets.math_font`, in kB of Brotli at quality 11.
- [budget/requests](https://docs.eyuan.me/codes/budget/requests/): A Page makes more requests on its render path than its Site budget, `budgets.requests`, allows.
- [budget/unknown-page](https://docs.eyuan.me/codes/budget/unknown-page/): An Acknowledged overage in `[budgets.overages]` names a URL that is no HTML Page of the Site, so it silences nothing.
- [config/deprecated](https://docs.eyuan.me/codes/config/deprecated/): A key in Site config has been renamed.
- [config/engine-version](https://docs.eyuan.me/codes/config/engine-version/): The project needs a different version of yuanme than the one running: `yuanme = "X.Y"` is the oldest compatible version, with Cargo's caret meaning, so 1.2 accepts any 1.x from 1.2 on and 0.3 accepts only 0.3.x.
- [config/invalid-value](https://docs.eyuan.me/codes/config/invalid-value/): A value in Site config has the right type but means nothing to yuanme: a URL that isn't absolute, a Route without its placeholder, an unknown field type, or a name that refers to nothing.
- [config/missing-key](https://docs.eyuan.me/codes/config/missing-key/): Site config leaves out a key that has no default.
- [config/out-of-range](https://docs.eyuan.me/codes/config/out-of-range/): A number in Site config is outside the range its key allows.
- [config/syntax](https://docs.eyuan.me/codes/config/syntax/): `yuanme.toml` is not valid TOML, so nothing else in it can be read.
- [config/unknown-key](https://docs.eyuan.me/codes/config/unknown-key/): Site config has a key yuanme doesn't know.
- [config/wrong-type](https://docs.eyuan.me/codes/config/wrong-type/): A key in Site config has a value of the wrong TOML type, such as a string where a number goes.
- [entry/duplicate-data-file](https://docs.eyuan.me/codes/entry/duplicate-data-file/): Two Data files share a name, such as `data/nav.toml` and `data/nav.yaml`, so `data.nav` would be ambiguous.
- [entry/duplicate-key](https://docs.eyuan.me/codes/entry/duplicate-key/): A key appears twice in the same mapping of front matter or a Data file, or an Org keyword that sets a field is given twice.
- [entry/duplicate-slug](https://docs.eyuan.me/codes/entry/duplicate-slug/): Two Entries in one Collection have the same Slug, so they would be written to the same URL.
- [entry/invalid-date](https://docs.eyuan.me/codes/entry/invalid-date/): A `date` or `datetime` field can't be read.
- [entry/invalid-slug](https://docs.eyuan.me/codes/entry/invalid-slug/): A `slug:` override isn't a valid Slug.
- [entry/invalid-value](https://docs.eyuan.me/codes/entry/invalid-value/): A field's value has the right type but isn't allowed: an `enum` value not in its list, a URL that isn't absolute, or an item repeated in a `unique` list.
- [entry/missing-field](https://docs.eyuan.me/codes/entry/missing-field/): An Entry, or an object inside one, leaves out a field that is required: `title`, or a declared field with neither `optional = true` nor a `default`.
- [entry/out-of-range](https://docs.eyuan.me/codes/entry/out-of-range/): A field's value is outside the `min` and `max` its Collection declares: a string's length in characters, or a number.
- [entry/output-collision](https://docs.eyuan.me/codes/entry/output-collision/): Two Routes, or a Route and a Static file, would write the same file of the Site.
- [entry/syntax](https://docs.eyuan.me/codes/entry/syntax/): An Entry's front matter, or a Data file, can't be read: it isn't valid YAML, TOML or JSON, its `---` is never closed, or the file isn't UTF-8.
- [entry/term-collision](https://docs.eyuan.me/codes/entry/term-collision/): Two different Terms of a Taxonomy end up with the same Slug, because a `slugs` override in `yuanme.toml` gives one the Slug of another.
- [entry/toml-front-matter](https://docs.eyuan.me/codes/entry/toml-front-matter/): An Entry starts with `+++` TOML front matter.
- [entry/unknown-key](https://docs.eyuan.me/codes/entry/unknown-key/): Front matter, or a Data file with a schema, has a key its Collection or schema doesn't declare, or an Org Entry has a keyword that is neither a field nor one of Org's.
- [entry/unknown-language](https://docs.eyuan.me/codes/entry/unknown-language/): A code block names a language that no grammar highlights, so it is shown as plain text.
- [entry/wrong-type](https://docs.eyuan.me/codes/entry/wrong-type/): A field has a value of the wrong type, such as a number where text goes.
- [host/cache-rule](https://docs.eyuan.me/codes/host/cache-rule/): A `[[host.headers]]` rule changes `Cache-Control` where yuanme's cache policy has to hold: on a hashed file in `/assets/`, which must stay `immutable`, or on a Page, which must revalidate with `max-age=0, must-revalidate` so that a deploy shows at once.
- [host/output-collision](https://docs.eyuan.me/codes/host/output-collision/): A Static file has the name of a file the Host adapter writes, such as `static/_headers` with the cloudflare or netlify adapter.
- [host/over-limit](https://docs.eyuan.me/codes/host/over-limit/): Site config has more header rules or redirects, or a longer line, than a host yuanme supports accepts.
- [host/redirect-conflict](https://docs.eyuan.me/codes/host/redirect-conflict/): A `[[host.redirects]]` rule redirects a URL the Site serves: a Page, a Static file, or a Page's URL without its trailing `/`, which hosts already redirect.
- [host/unsupported](https://docs.eyuan.me/codes/host/unsupported/): The Site's host can't do what the Site needs.
- [host/wrangler-mismatch](https://docs.eyuan.me/codes/host/wrangler-mismatch/): `wrangler.jsonc` doesn't serve the Site the way the cloudflare adapter writes it: `assets.directory` must be the output directory, `assets.html_handling` must be "auto-trailing-slash", the default, and `assets.not_found_handling` must be "404-page" for the Site's 404 Page to be served.
- [image/invalid](https://docs.eyuan.me/codes/image/invalid/): An image can't be processed: it isn't an image yuanme reads, it is damaged, it is over 100 megapixels, or it is a Static file, which is copied as it is.
- [image/missing-alt](https://docs.eyuan.me/codes/image/missing-alt/): An image in an Entry's body has no alt text, so a screen reader can only say that an image is there.
- [image/not-found](https://docs.eyuan.me/codes/image/not-found/): An image in an Entry's body, an `image` field or `image()` names a path where no image is.
- [image/remote](https://docs.eyuan.me/codes/image/remote/): `image()` is given a remote URL.
- [image/unoptimized](https://docs.eyuan.me/codes/image/unoptimized/): A Page loads a raster image over 50 KB as it is, at full size and in its own format: a Static file, an image a stylesheet's `url()` or a `<link>` names, or an animated GIF, WebP or PNG.
- [internal/panic](https://docs.eyuan.me/codes/internal/panic/): yuanme crashed while processing a file.
- [link/broken](https://docs.eyuan.me/codes/link/broken/): A Page links to, or loads, a URL of the Site where nothing is: no Page, Static file or asset of the build.
- [link/redirected](https://docs.eyuan.me/codes/link/redirected/): A Page links to a URL of the Site that hosts answer with a redirect, which costs the visitor a round trip: a Page's URL without its trailing `/` or with `index.html` on the end, a `.html` file, a `[[host.redirects]]` rule's `from`, or the Site's address with or without `www.`.
- [link/unresolved](https://docs.eyuan.me/codes/link/unresolved/): A link to another file or a fragment doesn't lead anywhere in the Site: no Entry has that file as its source, or the page has no element with that id.
- [markdown/empty-directive](https://docs.eyuan.me/codes/markdown/empty-directive/): A `:::` line opens a block directive with no name.
- [markdown/no-effect](https://docs.eyuan.me/codes/markdown/no-effect/): Something in a Markdown body is valid but changes nothing in the output, such as a `[title]` on a directive that isn't a Theorem block.
- [markdown/out-of-fuel](https://docs.eyuan.me/codes/markdown/out-of-fuel/): A Markdown body would take longer to parse than yuanme allows for its length, so the build stops instead of hanging.
- [math/duplicate-label](https://docs.eyuan.me/codes/math/duplicate-label/): Two things in one Entry have the same Label.
- [math/invalid-label](https://docs.eyuan.me/codes/math/invalid-label/): A Label has a character other than letters, digits, `:`, `_`, `.` and `-`.
- [math/named-environment](https://docs.eyuan.me/codes/math/named-environment/): An Org LaTeX environment has a `#+NAME`.
- [math/tex-delimiter](https://docs.eyuan.me/codes/math/tex-delimiter/): A Markdown paragraph has `\(…\)`, `\[…\]` or a bare `\begin{…}`, which Markdown doesn't read as math: there `\(` and `\[` are escaped brackets, as on GitHub and in Pandoc.
- [math/unknown-label](https://docs.eyuan.me/codes/math/unknown-label/): An `\eqref`, or an Org `\ref`, names a Label that no numbered equation in the Entry has.
- [math/unsupported](https://docs.eyuan.me/codes/math/unsupported/): Math uses LaTeX that yuanme can't render, or isn't valid LaTeX: an unknown command or environment, a group that is never closed, or `\label` outside a numbered environment.
- [org/duplicate-id](https://docs.eyuan.me/codes/org/duplicate-id/): Two Org Entries or headings have the same `:ID:` property, so an `id:` link to it could lead to either.
- [org/invalid-attribute](https://docs.eyuan.me/codes/org/invalid-attribute/): An `#+ATTR_HTML` line has text that isn't an attribute.
- [org/misplaced-keyword](https://docs.eyuan.me/codes/org/misplaced-keyword/): A keyword that sets one of the Entry's fields, such as `#+TITLE` or `#+DATE`, comes after the first headline or body text.
- [org/no-effect](https://docs.eyuan.me/codes/org/no-effect/): Something in an Org Entry is valid Org but changes nothing in yuanme's output, such as a keyword for Org's own exporter, an `#+OPTIONS` setting yuanme doesn't do, or a `#+CAPTION` on a paragraph.
- [org/out-of-fuel](https://docs.eyuan.me/codes/org/out-of-fuel/): An Org paragraph would take longer to parse than yuanme allows for its length, so the build stops instead of hanging.
- [org/setupfile](https://docs.eyuan.me/codes/org/setupfile/): An Org Entry has a `#+SETUPFILE`.
- [org/too-deep](https://docs.eyuan.me/codes/org/too-deep/): Blocks, lists or markup in an Org body nest inside each other too deeply for yuanme to parse.
- [org/undefined-footnote](https://docs.eyuan.me/codes/org/undefined-footnote/): An Org footnote reference names a footnote that is never defined.
- [org/unknown-option](https://docs.eyuan.me/codes/org/unknown-option/): `#+OPTIONS` has an option Org doesn't have, so it does nothing, in Emacs as in yuanme.
- [org/unsupported-construct](https://docs.eyuan.me/codes/org/unsupported-construct/): An Org body uses something outside the Org subset: macros, `#+INCLUDE`, `#+CALL` and other code that runs, citations, radio targets, dynamic blocks, inline tasks, headlines deeper than level 5, or a link type yuanme can't follow.
- [org/wrong-weekday](https://docs.eyuan.me/codes/org/wrong-weekday/): An Org timestamp in a date field names a day of the week that isn't the date's.
- [template/bad-filter-argument](https://docs.eyuan.me/codes/template/bad-filter-argument/): A filter or function got an argument it can't use: a missing or unknown one, a value of the wrong type, a `dateformat` format it doesn't know, or a `-` key passed to Jinja's own `sort`, which reads it as a field name.
- [template/bad-header](https://docs.eyuan.me/codes/template/bad-header/): A props comment on a Component, or a vars comment on a Layout, can't be read or doesn't match its macro: an entry that isn't `name: type` or `name?: type`, an unknown type, a props comment that isn't directly above a `{% macro %}`, a prop the macro doesn't have or a parameter the comment doesn't declare, or a macro in `templates/components/` with no props comment.
- [template/bad-prop](https://docs.eyuan.me/codes/template/bad-prop/): A call to a Component passes a prop it doesn't declare, leaves out one it requires, passes one of the wrong type or an optional value to a required prop, or gives a `{% call %}` body to a Component that takes none, or none to one that needs it.
- [template/bad-var](https://docs.eyuan.me/codes/template/bad-var/): A Template extends a Layout without setting a variable its vars comment requires, or sets one to a value of the wrong type.
- [template/compare-optional](https://docs.eyuan.me/codes/template/compare-optional/): A Template compares an optional field with `==`, `!=`, `<`, `in` or another comparison without a guard.
- [template/non-constant-name](https://docs.eyuan.me/codes/template/non-constant-name/): `extends`, `include` or `import` names a Template with an expression.
- [template/not-found](https://docs.eyuan.me/codes/template/not-found/): A Template that a Route renders, or that another Template extends, includes or imports, is not in `templates/`.
- [template/render](https://docs.eyuan.me/codes/template/render/): A Template failed while rendering a Page: it printed a value that is absent, reached through one, or did something its values don't allow.
- [template/syntax](https://docs.eyuan.me/codes/template/syntax/): A Template is not valid Jinja, so no Page that uses it can render.
- [template/undeclared-input](https://docs.eyuan.me/codes/template/undeclared-input/): A Component reads a variable it wasn't given: not one of its props, nor `site`, `data`, `collections`, `taxonomies` or `page`, which every Page sees.
- [template/unguarded-optional](https://docs.eyuan.me/codes/template/unguarded-optional/): A Template prints, loops over, filters or reaches through an optional field without a guard, so a Page whose Entry leaves it out fails to render.
- [template/unknown-block](https://docs.eyuan.me/codes/template/unknown-block/): A Template overrides a block that no Layout it extends has, so its content would never be shown.
- [template/unknown-field](https://docs.eyuan.me/codes/template/unknown-field/): A Template reads a field or a variable that isn't in the schema of what its Page sees: a typo, a field of another Collection, a value only another kind of Route has, such as `entries` on a Taxonomy's index, or a field of something that has none, such as a string.
- [template/unknown-filter](https://docs.eyuan.me/codes/template/unknown-filter/): A Template calls a filter, test or function that neither Jinja nor yuanme has, a macro its import doesn't define, or a method: Templates have no methods, such as Python's `.lower()`.
- [template/unknown-url](https://docs.eyuan.me/codes/template/unknown-url/): `url()` names a path that is no Route, feed or Static file of the Site, so the link would lead nowhere.
- [template/unscoped-tag](https://docs.eyuan.me/codes/template/unscoped-tag/): A Template with a Sidecar stylesheet writes a tag that yuanme can't scope, or can't check, as written.
- [template/wrong-type](https://docs.eyuan.me/codes/template/wrong-type/): A Template uses a value as a type it isn't, such as looping over a string or passing a list to `attrs`.