Reference

Trail derives the whole site from the tree, so every name in it is meaningful and every unrecognised name is a build error. This page is the exhaustive grammar. Anatomy of a site is the same material as a walkthrough.

The name shapes #

<order> #

A non-negative integer, parsed as written. 1, 100 and 007 are all valid and all mean their numeric value.

• It is a sort key only — never shown, never part of a URL — except inside a book, where it is the published section number.
• Gaps are fine and normal.
• Two siblings sharing an order is an error, since their relative order would then depend on nothing visible.
• Anything not parseable as an integer is an error: no 1.5, no -1, no first.

a<N> — appendix orders #

Inside a book only. An order written a1, a2, … marks an appendix entry, which is lettered rather than numbered and sorts after every numbered sibling at its level.

• Letters are bijective base 26: a1 → A, a26 → Z, a27 → AA.
• The letter comes from the number, not from position, so gaps show through here too.
• a0 is an error: appendix orders start at a1.
• Outside a book, an a<N>-- prefix is just a non-numeric order prefix, and therefore an error.

<slug> #

Lowercase kebab-case:

ASCII lowercase letters, digits and hyphens
not empty
not starting or ending with a hyphen

getting-started, pgss, rfc-2119 are fine. Getting_Started, -draft, tokens/, café are not.

The slug is the URL segment, and it is what you write in a ~link.

<kind> #

Exactly one of antho, topic, book, shelf. Any other suffix is an error, as is a grouping directory with no suffix at all in a place where one is expected.

What each directory may contain #

Anything not listed is a build error. Entries whose name starts with . are skipped everywhere, so .git, .DS_Store and editor droppings are invisible to trail.

The dividing line: directories that hold groupings hold no files but trail.toml; directories that hold articles hold no grouping directories.

trail.toml by level #

Unknown keys are errors at every level. Where title is optional and absent, it is derived from the slug: hyphens to spaces, each word capitalised (the-two-gates → "The Two Gates").

Reserved names #

Images #

A co-located image is <slug>.<ext> where the stem is a valid slug and the extension is lowercase and one of:

png   jpg   jpeg   gif   svg   webp   avif

Anything else in an article directory falls through to the "unexpected file" error.

Sorting #

Siblings sort by order, ascending. Inside a book, appendix entries sort after every numbered entry at the same level, whatever their numbers.

Products are the exception: no order prefix, so they sort by the root config's featured list first (in that list's order), then the rest by title.

Duplicates #

Within one container, both order and slug must be unique:

items 'concepts' and 'guides' share order 1
duplicate article slug 'overview'

The noun is item for a container's mixed children (topics, books, anthologies, shelves), and article inside a topic subfolder or where only articles can sit. Slugs are reported without their order prefixes.

Shelf contents are checked flattened into their parent, because a shelf adds no URL segment — two shelves in one product cannot both hold a getting-started topic, since both would want the same URL.

URLs #

A page's URL is the product slug, then the slug of every container between it and the page, with two exceptions: shelves contribute nothing, and order prefixes contribute nothing.

peios.product/1--security.antho/2--tokens.topic/300--issuing/100--flow.md
  →  /peios/security/tokens/issuing/flow

Pages are written to disk as <path>/index.html.

trail.toml appears at every level of the tree, with a different schema at each. Unknown keys are build errors everywhere, so a typo fails loudly instead of doing nothing.

The site root #

Required at the site root. Four keys are mandatory.

sitename = "Peios Learn"
title = "Documentation for everything Peios"
description = "Concepts, guides, and reference for the Peios operating system…"
url = "https://learn.peios.org"
accent = "#3b82f6"
featured = ["peios", "pekit", "provium", "universal-directory", "trail"]
footer = "Peios Learn — documentation for the Peios project."

[[nav]]
label = "Specs"
url = "~peios/pgss"

Validation #

• accent and accent_dark must be #rrggbb. accent_dark without accent is an error.
• custom_css, favicon and head_html are paths relative to the site root, and the file must exist. Naming one is also what makes it legal to keep in the site root; the first path component is what is tolerated there.
• edit_url must contain the literal {path}, which is replaced with the article's source path relative to the site root.
• Every slug in featured must name an existing product.

passthrough #

Root entries trail neither builds nor understands, copied into the output as they are:

passthrough = ["CNAME", ".well-known", "ads.txt"]

Each entry is a plain relative path naming a file or a directory that exists in the site root; directories are copied whole, nesting included. Naming an entry is also what makes it legal to keep in the site root, exactly as favicon and friends do — so this is how a repository that is also a trail site keeps its CNAME beside its trail.toml.

Errors: an entry that is empty, absolute, or contains ..; one naming something that does not exist; one naming the build output directory.

Passthrough entries are copied last, after everything trail generates, so an entry deliberately named after a generated file replaces it. Naming robots.txt is a supported way to ship your own; naming assets would bury the stylesheet, and trail will not stop you.

[[nav]] #

References here are resolved strictly at load time — a broken nav link fails the build even under --allow-dangling-links, because site chrome appears on every page.

A shelf is not a link target, so a nav entry cannot point at one — aim at the anthology above it, or a page inside it.

What url unlocks #

Without it: no sitemap.xml, no Sitemap: line in robots.txt, no og:url, relative canonical URLs, and relative outward links in /print bundles. Set it before deploying.

A product #

Required in every <slug>.product directory.

title = "pekit"
monogram = "pk"
color = "#22c55e"
description = "The recipe-driven build and packaging tool."
inline_ref = ["pekit"]

An anthology #

Required in every .antho directory.

A book #

Required in every .book directory.

title = "Peios Generic System Standards"
short = "PGSS"
description = "Cross-platform system standards from the Peios Project"
inline_ref = ["PGSS", "Peios Generic System Standards"]

A topic, subfolder or chapter #

Optional. Both keys are optional.

title = "Reference"

A shelf #

Optional, and takes title only.

inline_ref on a shelf is an error. A shelf has no page and no articles of its own, so the phrase would have nowhere to land — declare it on the shelf's items instead.

Derived titles #

Wherever title is optional and absent, it comes from the slug: hyphens become spaces and each word is capitalised. 2--writing-tests.topic becomes "Writing tests"; the-two-gates becomes "The Two Gates". Write the key when that is wrong — acronyms, proper nouns, unusual casing.

inline_ref everywhere #

The key means the same thing at every level: a list of phrases that should become links to this thing wherever they appear in the site's prose. Phrases are exclusive site-wide — two declarers claiming one phrase is an error — and must not be empty, carry leading or trailing whitespace, or contain §. See Inline references.

Every article begins with a YAML frontmatter block: a line of exactly ---, the keys, and a closing ---. It must be the first thing in the file. Unknown keys are build errors.

---
title: Command-line reference
type: reference
description: Every pekit flag with its value form, the capability matrix, and exit codes.
related:
  - pekit/running/invocation
  - pekit/reference/recipe-format
inline_ref:
  - pekit CLI
updated: 2026-05-01
reading_minutes: 25
---

The keys #

title #

The page's name: its h1, breadcrumb, sidebar entry, search-result heading and og:title. Never derived — an article always states its own.

type #

The learn taxonomy. Required on articles in topics; an error on articles in books, where the question it answers is already settled by the document's order.

Trail does not constrain the value and does not display it on the page. It is carried into site.json as the article's type. This site uses concept, how-to and reference.

description #

One sentence. It feeds:

• <meta name="description"> and og:description;
• the standfirst line of the page's markdown mirror;
• the description field in site.json.

It is not shown on the page, and it is not the in-site search snippet — Pagefind builds those from body text.

--strict fails the build on any article without one. Alias pages are exempt.

related #

Page references in the ~ grammar, without the leading ~:

related:
  - pekit/running/invocation
  - peios/package-management/overview

They render as a "Related Content" list under the article, appear in the markdown mirror, and become a list of resolved paths in site.json.

Resolution is as strict as a body link: ambiguous references always fail the build; missing ones fail unless --allow-dangling-links downgrades them to a warning, in which case they are dropped from the list.

inline_ref #

Phrases that should link to this article wherever they appear in the site's prose:

inline_ref:
  - PCDS GUID
  - PCDS GUIDs

Matching is literal, whole-word and longest-first, and skips headings, links, image alt text, code, and the claiming page itself. A phrase belongs to exactly one declarer site-wide; a collision is a build error, as is an empty phrase, one with leading or trailing whitespace, or one containing §. Alias pages claim nothing. See Inline references.

updated #

An ISO YYYY-MM-DD date, validated as such:

updated: '2026/05/01' is not an ISO date (expected YYYY-MM-DD)

It appears in the page's meta line and becomes the page's <lastmod> in sitemap.xml. Containers take the most recent date beneath them.

Deliberately manual: file modification times are noise, and trail does not read git history.

reading_minutes #

An integer overriding the estimate, which is otherwise the body's word count at 200 words a minute, rounded up, with a floor of 1. Code blocks count toward the word count.

Containers sum their children's values, so a book cover reports the whole book.

Errors #

Inside a book, type: produces an unknown-key error, since type is not part of the book article schema.

Frontmatter and .link aliases #

An alias page has no frontmatter of its own — it renders the target's body. It takes its title from the .link file (or from its own slug), its canonical URL from the original, and it claims no inline_ref phrases. Inside a book it also loses type and description, as every book entry does.

Trail has two commands, build and serve, plus clap's own help. Everything below is the complete flag surface; there are no others.

Synopsis #

trail build [OPTIONS] [ROOT]
trail serve [OPTIONS] [ROOT]
trail help  [COMMAND]

trail --version prints the version; trail --help and trail <command> --help print usage.

trail build #

Builds the site into the output directory.

On success:

built 1227 pages (8 products) → ./dist

With --cbpath, a second line names the copy:

built 1227 pages (8 products) → ./dist
cache-busting copy → ./dist/8f3a91c/

The page count is the site's; the copy holds the same number again and is not added in.

The count is HTML pages: articles, product and anthology landings, book covers, /print pages, the front page and 404.html. Markdown mirrors, llms.txt, site.json, the sitemap and the search bundle are not counted.

trail serve #

Builds the site, serves the output over HTTP, and rebuilds on change. Takes every build flag, plus:

serving ./dist at http://127.0.0.1:8724 (watching . for changes)
rebuilt 1227 pages

Behaviour:

• Changes are debounced for 200 ms; changes inside the output directory, and paths with a dot-prefixed component, are ignored.
• Pages are served with a live-reload script that reloads them over server-sent events after each successful rebuild. trail build output never contains it.
• Misses serve the built 404.html with a real 404 status.
• A failed initial build or rebuild prints the error and keeps serving the last good output — the process does not exit.

Exit status and streams #

trail serve runs until interrupted.

Warnings #

These print on stderr and do not fail the build:

Errors #

Loading errors stop at the first problem, with the chain of contexts:

Error: loading product 'pekit'

Caused by:
    0: loading topic in '2--recipes.topic'
    1: in article '100--anatomy.md'
    2: updated: '2026-5-1' is not an ISO date (expected YYYY-MM-DD)

Link errors are collected across the whole site and reported together:

Error: 3 broken links:
in article '/pekit/recipes/anatomy': link '~pekit/running/invokation' matches no page in product 'pekit'
…

The common ones #

Installing #

Trail is a single Rust binary. Build it from its source directory:

$ cargo build --release

The result is target/release/trail. It carries the templates, stylesheet, fonts, syntax definitions, search engine and diagram renderer inside it, so the binary alone is the whole tool — copy it onto your PATH and nothing else needs installing.