--- title: Glossary description: Look up what each word in this manual means, from corpus, slug, and route to shell, finding, refusal, and the four machine files. slug: /concepts/glossary order: 1 visibility: public redirects_from: [] --- # Glossary 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](/reference/page-source/#front-matter) 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](/reference/page-source/#slugs) 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](/reference/page-source/#order) 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](/guides/code-blocks/) 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](/guides/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](/guides/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](/reference/output/#publication-and-recovery) says what a failure leaves in it. ### Shell A complete HTML document of the site's own, given with `--shell`, containing the two markers `` and ``. The build renders every page into it, and [Style the site](/guides/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](/reference/output/#the-styling-surface) 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](/reference/refusals/#usage-errors) lists each one. ## The output ### Tree The folder the build writes. [Output](/reference/output/#the-tree) 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](#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](/reference/output/#the-manifest) 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](/reference/output/#the-whole-text) 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](/reference/refusals/) 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](/reference/page-source/#heading-anchors) gives the rule. ## Related - [What happens without asking](/concepts/what-happens-without-asking/) lists what the tool reads, writes, and never does. - [Page source](/reference/page-source/) gives the slug, front-matter, order, and link rules behind these words.