Glossary #

View this page as Markdown

This page defines each word the manual uses, with a link to the page that gives its rules. The words are grouped by where they occur: the source you write, the build you run, the output it writes, and the check that reads the source.

The source #

Corpus #

A folder of Markdown files with front matter, the input to one build. The folder given with --source is the corpus's root, and each subfolder containing an index.md is a section.

Page #

One Markdown file in the corpus, rendered as one HTML page at its slug. A page has a title, an optional description, a slug, an order, a visibility, a list of old slugs that redirect to it, and an optional section word for the manifest.

Front matter #

The metadata block at the start of a page, between two --- lines. The parser accepts seven keys, title, description, slug, order, visibility, redirects_from, and section, and only title is required. Page source gives the rules.

Title #

The page's name, shown in the navigation, the page head, the index, and the manifest. It is the only required front-matter key.

Description #

One sentence stating what the page lets the reader do, written into the page head, the index line, and the manifest row. It is empty by default.

Slug #

The page's path within the site, with a leading slash and no trailing slash, such as /guides/first-guide. It comes from the file path unless the front matter declares one. Page source gives the rules.

Route #

A slug with the base path in front of it and a trailing slash, as written into the manifest, the index, and the whole text. With --base /docs, the slug /guides/first-guide has the route /docs/guides/first-guide/.

Tree-relative #

Written from the tree root, as a leading-slash path without the base path in front of it. A slug, a redirects_from entry, and the prefix given to --full-text-exclude are tree-relative. /reference is tree-relative, and /docs/reference/, with the base path, is a route.

Base path #

The path the site is served under, given with --base. The build writes it into the routes of the index, the manifest, and the whole text and, given --origin, into each page's canonical link and og:url tag. The pages link relatively.

Section #

A subfolder containing an index.md, shown in the navigation as a group the reader opens and closes where it contains other pages. Its index page's title gives it its name, and a section inside a section is a subsection. In the manifest, a page's section is its slug's first segment, or home for the home page. A page can declare another word with its section key, and the check reports a word that names no top-level section. A subfolder without an index.md is not a section. Its pages appear among the entries of the section above it.

Index page #

A folder's index.md. Its title gives the section its name, and its order places the section among its parent's entries. In a section that contains other pages, it has only front matter, and the build makes no page from it. In a section of one page, it is that page, at the folder's slug.

Home page #

The corpus root's index.md, at the slug /. Its title heads the index, and its description is the index's block quote.

Order #

A front-matter integer that places a page among its siblings, or, on an index page, the section among its parent's entries. Page source gives the sort rules.

Visibility #

The front-matter key that says whether a page is built. public, the default, builds the page. Any other value leaves the page out of the pages, the navigation, and every machine file unless the build passes --include-hidden.

Redirect stub #

The index.html the build writes at each old slug listed in a page's redirects_from, sending the reader to the page's current slug. A stub is not a page: it has no navigation, no shell, and no entry in any machine file.

Code block #

A fenced block in a page, highlighted at build. The text after the opening backticks is the info string: a language word, then optionally a title and a line set. Highlight a code block gives the fence line.

Line set #

The part of an info string in braces, such as {2,5-6}, listing the lines of the block to emphasize, counted from 1.

Callout #

A block quote whose first line is one of five markers, such as [!NOTE] or [!WARNING], shown with a title and a colored bar, as on GitHub. Add callouts and diagrams gives the markers.

Diagram #

A fenced block marked mermaid, drawn as an image in the reader's browser where Mermaid is installed for the build, and shown as a code block otherwise. Add callouts and diagrams says how to install it.

The build #

Build #

The command tzdocs build, which checks the corpus and the output folder, generates the site in a staging folder, and then replaces the output folder with it.

Output folder #

The folder given with --out. A successful build replaces its entire contents, so keep it outside the source folder and containing nothing else.

Staging folder #

A temporary .tzdocs-stage-* folder beside the output folder, where the build generates the new site before it replaces the output folder.

Backup folder #

A temporary .tzdocs-backup-* folder beside the output folder, keeping the previous site while the build replaces it. Output says what a failure leaves in it.

Shell #

A complete HTML document of the site's own, given with --shell, containing the two markers <!--tzdoc:head--> and <!--tzdoc:page-->. The build renders every page into it, and Style the site explains it.

Default layout #

The HTML document the tool renders each page into when the build is given no shell. Its body has the class tzdoc-page.

Home opening #

An HTML fragment, given with --home-opening, placed at the head of the home page's article column and nowhere else.

Site stylesheet #

A CSS file, given with --stylesheet, copied into the tree as site.css and linked after the tool's own docs.css on every page.

Styling surface #

The class names, attributes, custom properties, and selectors in the generated pages that a site stylesheet or a shell's stylesheet targets. Output lists them.

Usage error #

A command line the tool cannot read, such as an unknown flag or a flag without its value. The tool prints the reason and the usage lines and exits with code 2. Refusals and findings lists each one.

The output #

Tree #

The folder the build writes. Output lists what it contains.

Copy control #

A button at each code block's right that copies the block as authored, plus one trailing newline. The page's one inline script places it, and on a page with a diagram the same script starts Mermaid.

Machine files #

The four kinds of file every build writes for scripts and AI agents: the index, the manifest, a Markdown copy of each page, and the whole text.

Index #

The file llms.txt at the tree root: the corpus's title, its description, and one line per page with its title, route, and description, grouped by section. An agent reads it first.

Manifest #

The file docs.json at the tree root, listing every page's route, title, description, section, whether the whole text holds it, and headings with their anchors. It also lists each route a page moved from, beside the page's route. Output lists its members.

Markdown copy #

The file index.md beside each page's index.html: the page's source, front matter included, with line endings normalized.

Whole text #

The file llms-full.txt at the tree root: every built page's source in navigation order, except the pages under the prefix given to --full-text-exclude. Output gives its form.

Corpus version #

The text given with --corpus-version, written as the manifest's top-level version, so that an agent can read which version of the product the corpus describes.

The check #

Check mode #

The command tzdocs check, which checks the corpus, prints one line per finding, writes nothing, and exits with code 1 when there is any finding.

Finding #

One line the check prints, giving the source file and what is wrong with it. A finding is either a refusal or an advisory finding.

Refusal #

A finding on which the build writes nothing, such as two files with one slug or malformed front matter. The build also refuses on its own checks, such as an output folder that overlaps the source. Refusals and findings lists every one.

Advisory finding #

A finding on which the build still proceeds, such as a link whose fragment matches no heading anchor, or a code fence whose metadata does not parse. A link to a missing page is not one: it refuses the build. The check still exits with code 1 on it.

Heading anchor #

The id the build gives a heading, which a link's fragment must match. Page source gives the rule.