Configuration

A path relative to the documentation root, and it must be a file the renderer can see. Put it beside the documents, so the render copies it into the output. A file that only exists on the build machine is not in the site. _images/ is the conventional place.

The mark is a link like every other picture, so any format works. The file's own colours draw it: the same mark in light and in dark. Write an SVG's colours as var(--token, #hex) anyway. Artwork says what that buys, and what Firefox and Safari have to ship before a mark can take the page's ink.

A signet is not an icon. It ships at three optical sizes with different construction, and bar height is the small one's job. Brand says which file to hand over.

The mark in the tab. Once per file, not as one path, because a browser picks between them at the link. sizes is the slot of a file, spelt as the attribute is. One entry can leave it out as the file for everything else. Paths follow the signet's rule: inside the documentation tree, where the renderer can see them.

Set nothing, and the signet is the tab icon, the right answer for a project with one drawing. A bar with a mark above a tab without one is a site that says two things. Set the sizes where there is more than one drawing. This system ships three, at three optical sizes, because a favicon slot cannot scale one. A media query inside the file cannot pick either. As a link, an SVG only sees its own viewport.

The name in the bar, when it is not the project's own title. A manual that documents one product inside a larger project says the product.

Whose product it is, where that is a second name. It becomes the first half of a lockup, with the accent rule between the two halves, one of exactly three places that colour appears. With no brand the mark is one name in the mark's own weight. A single name is not the quiet half of a lockup with nothing beside it.

Where the mark leads. Resolved as an asset path, for a manual under a marketing page outside the rendered project. Without it the mark leads to /index.

href is a document, /guide/index, as a :doc: reference spells it. With external="true" it is a URL, opens in a new tab and carries the external marker.

label names the second kind only. A document's own :navigation-title: names it, everywhere.

A section is current on its own page and on every page under it, which is the toctree walked upwards. A page three levels inside the guide still marks Guide. A mark on the exact page only leaves the bar silent on all but a few pages.

The pages either side of this one, as two links at the end of the column. The order is the toctree flat: the order of the rail, and the order of a read from front to back, with the root first. A toctree lists what is under a page and never the page it stands on.

Off unless a project says otherwise, and that is a decision, not caution. The renderer computes no such thing, so this is the theme with a path on offer. In a reference nobody reads front to back, that path is a row of noise under every page. A manual with a reading order says true.

A page outside the tree gets no row. A reader reaches an orphan from somewhere else. A way onward from a page that is not on the way is a path this theme invented.

The same documents, a second time as Markdown: page.md beside page.html, and every page names its own twin:

<link rel="alternate" type="text/markdown" href="stylesheets.md" />
<link rel="canonical" href="stylesheets.html" />

It is a second output format, not a conversion of the page. The renderer writes both from the same parsed document, node by node. So a directive decides what it is in Markdown the same way it decides what it is in HTML. What has no shape in Markdown, a grid or a band, is what it holds, not a box drawn in characters.

The format's name is the file extension every reference inside it resolves to. That makes the twin a site of its own. A link from one twin lands on the next twin, and nothing that follows those links ever gets a page.

The dialect is GitHub Flavoured Markdown, the one with a table, a fenced block with its language, a footnote and an alert. An admonition comes out as > [!WARNING]. The document's own anchors go into it too, one `<a id>` above every heading and wherever a label stands. A reader that derives them from the words derives them its own way, and a reference with a fragment has to land.

What the page carries in its head, the twin carries as front matter. It is the first byte of the file, because that is the only place a reader reads front matter as such:

---
title: "How the stylesheets are written"
description: "The class layer is one vocabulary written by many hands, …"
canonical: stylesheets.html
navigation-title: "Stylesheets"
---

title is the page's. canonical is the page this file is the twin of, the same relative name the page writes in its own rel="canonical". So the pair points both ways. description is what the page says it is about. An :abstract: field or a description in .. meta:: where the author wrote one, and the first sentence of the first paragraph where they did not.

Every other field above the title lands under its own name: :author:, :date:, :copyright:, the rest of .. meta::. A field that speaks to the renderer and says nothing to a reader, like :orphan: or :nosearch:, lands nowhere. Every value carries quotes. The plain form is a list of exceptions, yes a boolean and 2024 a number. A title falls into one of them one day, and nobody reads it.

The same setting writes llms.txt at the publish root: the site's own table of contents, which a reader with no navigation lacks. It is the toctree. A heading per section, a line per page with the same description its twin opens with, and every link a twin.

A twin lands at its page's own path. A project can keep a .md file as an asset beside a document of the same name, a prompt, a snippet. The twin then overwrites it. Name one or the other something else. This site keeps its prompts under names no page carries.

On unless a project says otherwise, and that is the decision. A reader that is a program, an agent on a link, a model asked to read the manual, is a reader this theme has. A page with navigation, scripts and a frame is none of what it came for. Off is for a project that does not want its documents published twice.