# Trail
> The static site builder behind Peios Learn.
---
# What is Trail
_Trail / Getting started_
> Trail is the static site builder behind Peios Learn — a single Rust binary that turns a directory tree of markdown into a searchable, themed documentation site, with the structure coming from the filesystem rather than a config file.
**Trail** is a static site generator for documentation. You give it a directory of markdown files arranged into named folders; it gives you a complete website — every page rendered, cross-linked, indexed for search, mirrored as markdown for machines, and bundled into printable single-page views.
This site is built with it. Everything you are reading, including this page, comes out of one `trail build`.
## The one idea: the tree is the site
Trail has no table-of-contents file, no `sidebar.json`, no list of pages to keep in sync with the pages themselves. **The directory tree is the navigation.** A folder named `2--writing.topic` is a topic called "Writing" that sorts second; the `.md` files inside it are its articles, in the order their own numeric prefixes give them.
```text
learn/
├── trail.toml # the site
└── trail.product/ # a product
├── trail.toml
├── 1--getting-started.topic/ # a topic, sorted first
│ ├── 100--what-is-trail.md # an article, sorted first
│ └── 200--quick-start.md
└── 2--structuring-a-site.topic/
└── 100--products.md
```
Add a file, and the page exists, appears in the sidebar, joins the search index, and gets a markdown mirror. Rename a folder, and the section moves. Nothing else has to be told.
The trade is that names carry meaning. `100--quick-start.md` is not a decorative filename: `100` is the sort key and `quick-start` is the URL segment. [Directory and file names](/trail/reference/directory-names.md) is the exhaustive grammar; [Anatomy of a site](/trail/getting-started/anatomy-of-a-site.md) is the guided tour.
## Strict by default
The second principle is that **mistakes are build failures, not silent surprises**. A documentation site that quietly drops a page is worse than one that refuses to build.
- A key that `trail.toml` does not define is an error, not an ignored line.
- A file trail does not recognise — a stray `notes.txt` in a topic, a `README.md` without an order prefix — is an error, not a file left out of the site.
- A `~link` whose target no longer exists fails the build. Every broken link in the site is reported at once, so one run tells you the whole story.
- An ambiguous `~link` — one matching two pages — always fails, even under `--allow-dangling-links`. Trail will not guess which page you meant.
- A frontmatter `updated:` that is not an ISO date, a colour that is not `#rrggbb`, a `.link` alias pointing at another alias: all errors.
The escape hatches are deliberate and few. `--allow-dangling-links` downgrades missing targets to warnings while you are mid-refactor; that is the whole list.
## One binary, no runtime
Trail is a single Rust binary with everything compiled in: the templates, the stylesheet, the fonts and their licences, the search engine, the syntax highlighter, the diagram renderer. There is no theme directory to install beside it, no Node toolchain, no `npm install` step, and nothing to fetch at build time.
The output is equally plain. `dist/` is a directory of static files — HTML, CSS, WOFF2, JSON, a WASM search core — that any static host will serve as-is. There is no server component and no build step at request time.
## What one build does
```text
trail.toml + the tree
→ load parse every trail.toml and every frontmatter block, validate names
→ resolve .link aliases, ~link targets, inline-reference phrases, images
→ render one HTML page per article, product, anthology and book cover
→ export .md mirrors, /print bundles, llms.txt, site.json, sitemap, robots
→ index the Pagefind search bundle, built from the rendered pages
→ prune delete anything in dist/ this build did not write
```
Loading is where nearly all the errors live: by the time rendering starts, the site model is known to be well-formed. Pruning is why `dist/` belongs entirely to trail — a page you deleted from the source disappears from the output on the next successful build, along with superseded search index fragments and stale images.
Builds are fast enough not to think about. This site — over twelve hundred pages — builds from scratch in a little over three seconds.
## What a site is made of
Four kinds of thing, from the outside in:
| | What it is |
|---|---|
| **Site** | One `trail.toml` at the root, the front page, and the products. |
| **Product** | A documented thing (`trail.product/`) with its own colour, monogram and landing page. |
| **Grouping** | How a product's pages are organised: [anthologies](/trail/structuring-a-site/anthologies-and-shelves.md), [topics](/trail/structuring-a-site/topics-and-folders.md), [books](/trail/structuring-a-site/books.md) and shelves. |
| **Article** | One `.md` file: YAML frontmatter, then markdown. |
The distinction that matters most is **topic versus book**. A topic is a set of articles you can read in any order — a how-to section, a concept section. A book is a formal, ordered document — a specification, a reference manual — with a cover page, dotted section numbers (`2.1.3`), chapters that nest arbitrarily deep, and lettered appendices. They render differently because they are read differently.
## What trail gives readers
Beyond the pages themselves, every build produces:
- **Search** — a ⌘K modal over a [Pagefind](https://pagefind.app) index, loaded lazily so pages carry no search cost until someone searches. Results carry the query through to the page, which highlights every match.
- **Three-state theming** — light, dark, or follow the system, remembered per reader. Syntax highlighting, diagrams and images all follow it.
- **Print and machine views** — every topic, book, anthology and product is also one long page at `/print`, one markdown file at `/print.md`, and every individual page is mirrored at its own URL with `.md` appended.
- **The reading furniture** — a scroll-spying "On this page" list, copy buttons on code blocks, heading permalinks, adjustable text size, previous/next links, a mobile drawer, and a back-to-top button.
[The reading experience](/trail/building/the-reading-experience.md) covers all of it; [The output surface](/trail/building/the-output-surface.md) covers exactly what lands in `dist/`.
## What trail is not
- **Not a general-purpose SSG.** There is no plugin system, no shortcode API, no way to add a page type. The templates are compiled in and are not user-replaceable; [theming](/trail/building/theming.md) happens through CSS custom properties and an optional stylesheet.
- **Not versioned.** One build produces one version of the site. Hosting several versions means several builds at several paths.
- **Not incremental.** Every build renders every page. It is fast enough that this has never mattered.
- **Not a subpath host.** Sites are served from the root of a domain; internal links are root-relative.
## Where to start
If you want a working site in five minutes, go to the [Quick start](/trail/getting-started/quick-start.md).
If you want to understand the layout before writing anything, read [Anatomy of a site](/trail/getting-started/anatomy-of-a-site.md), then the [Structuring a site](/trail/structuring-a-site/products.md) section in order.
If you are writing pages in a site that already exists, [Writing](/trail/writing/articles-and-frontmatter.md) is the section you want — frontmatter, links, images, code blocks and the rest.
---
# Quick start
_Trail / Getting started_
> Build a documentation site from an empty directory — a root trail.toml, one product, one topic, one article — then serve it with live reload and watch it grow.
This page takes you from an empty directory to a served, searchable documentation site in about five minutes. You will write four files, run `trail build`, look at what it produced, then switch to `trail serve` and add a second page while it is running.
## Prerequisites
- **A `trail` binary.** Trail is a single Rust binary; build it from its source directory with `cargo build --release` and the result is `target/release/trail`. Put it on your `PATH`, or call it by path — the examples below assume `trail` is on your `PATH`.
- **Nothing else.** The templates, stylesheet, fonts, syntax highlighter, diagram renderer and search engine are all compiled into the binary.
## Create the site
A trail site is a directory with a `trail.toml` in it. Make one:
```console
$ mkdir acme-docs && cd acme-docs
```
```toml
# acme-docs/trail.toml
sitename = "Acme Docs"
title = "Documentation for Acme"
description = "Guides and reference for the Acme toolchain."
footer = "Acme — docs."
```
Those four keys are the only required ones. `sitename` is the wordmark in the header (its last word is accented); `title` and `description` are the front page's headline and standfirst, and feed the site's `` tags. Everything else — the accent colour, the base URL, header links, a favicon — is optional and covered in [Configuring the site](/trail/building/configuring-the-site.md).
> [!NOTE]
> The site root may contain **only** `trail.toml`, `*.product` directories, the build output directory, and any files named by the config (a favicon, a custom stylesheet). Anything else is a build error. This is deliberate: a stray file in the root is far more likely to be a mistake than a plan.
## Add a product
Every page belongs to a **product** — a documented thing with its own landing page, colour and monogram. Products are directories named `.product`:
```console
$ mkdir -p docs.product
```
```toml
# acme-docs/docs.product/trail.toml
title = "Acme CLI"
monogram = "ac"
color = "#3b82f6"
description = "The command-line interface to Acme."
```
All four keys are required. The directory name gives the URL (`/docs`) and the slug you link by; `title` is what readers see. The `monogram` is the two-or-so characters shown on the product's tile on the front page, and `color` tints the product's cards, sidebar and headings.
## Add a topic and an article
A **topic** is a set of articles read in any order. Topics are directories named `--.topic`:
```console
$ mkdir -p docs.product/1--guides.topic
```
```markdown
---
title: Hello
type: how-to
description: The first page.
---
Hello from **Acme**.
```
Three things are going on in that filename and that frontmatter block:
- **`1--guides.topic`** — the `1` sorts this topic among its siblings and never appears in a URL; `guides` is the URL segment; `.topic` is the kind. With no `trail.toml` of its own the topic's title is derived from the slug ("Guides").
- **`100--hello.md`** — same grammar for articles. Numbering in hundreds is a convention, not a rule: it leaves room to insert `150--` later without renumbering.
- **`title:` and `type:`** are the two required frontmatter keys. `description:` is optional but worth writing — it becomes the page's meta description and its social-preview text.
## Build it
```console
$ trail build
```
```text
built 6 pages (1 products) → ./dist
```
Six pages from one article, because trail writes more than the pages you authored:
```console
$ find dist -type f -not -path 'dist/assets/*' -not -path 'dist/pagefind/*'
```
```text
dist/index.html the front page
dist/404.html the not-found page
dist/docs/index.html the product landing page
dist/docs/guides/hello/index.html your article
dist/docs/print/index.html all of Acme CLI on one page
dist/docs/guides/print/index.html all of Guides on one page
dist/docs.md the product, as markdown
dist/docs/guides/hello.md your article, as markdown
dist/docs/print.md all of Acme CLI, as one markdown file
dist/docs/guides/print.md all of Guides, as one markdown file
dist/llms.txt the site's map for language models
dist/site.json the site's structure, machine-readable
dist/robots.txt
```
Plus `dist/assets/` (the stylesheet and fonts) and `dist/pagefind/` (the search index and its WASM core). Note that there is no page at `/docs/guides` — a topic has no page of its own. It shows up as a card on the product page, and links to it land on its first article.
`dist/` belongs to trail: at the end of every successful build it deletes anything in there that the build did not write.
## Serve it
```console
$ trail serve
```
```text
serving ./dist at http://127.0.0.1:8724 (watching . for changes)
```
`trail serve` builds the site, serves it, and watches the source tree. Save a file and the browser reloads itself; break something and the error prints in the terminal while the last good output keeps being served.
Open the site and try it: press ⌘K (or Ctrl K) to search, and use the theme button in the header to switch between light, dark and system.
## Add a second page
Leave the server running and add another article beside the first:
```markdown
---
title: Installing
type: how-to
description: How to install Acme.
related:
- docs/guides/hello
---
See [Hello](~docs/guides/hello) first.
```
Two new things:
- **`~docs/guides/hello`** is a page reference, not a URL. The first segment names a product; the rest matches the end of a page's path. Move or rename the target and the link still resolves as long as its slug is unchanged; delete it and the build fails rather than shipping a dead link. See [Links and references](/trail/writing/links-and-references.md).
- **`related:`** takes the same references (without the `~`) and renders a "Related content" list at the foot of the page.
Save, and the page appears in the sidebar next to Hello.
## Where to go next
- [Anatomy of a site](/trail/getting-started/anatomy-of-a-site.md) — the whole tree, level by level, with a real example.
- [Products](/trail/structuring-a-site/products.md) — the structuring section in order: products, anthologies, topics, books.
- [Articles and frontmatter](/trail/writing/articles-and-frontmatter.md) — every frontmatter key and what it does.
- [Configuring the site](/trail/building/configuring-the-site.md) — the base URL, accent colour, navigation links, edit links and the rest of `trail.toml`.
---
# Anatomy of a site
_Trail / Getting started_
> The whole tree, level by level — how directory and file names become URLs, ordering and titles, which trail.toml lives where, and what may legally sit at each level.
A trail site is a directory tree in which every name means something. This page walks that tree from the root down, and explains the naming grammar all of it shares. [Directory and file names](/trail/reference/directory-names.md) is the same material as an exhaustive table; [Structuring a site](/trail/structuring-a-site/products.md) covers each kind of container in depth.
## The whole shape
```text
learn/ the site root
├── trail.toml the site config — required
├── dist/ the build output — trail's to manage
│
├── peios.product/ a product → /peios
│ ├── trail.toml required: title, monogram, color, description
│ ├── 1--security-fundamentals.antho/ an anthology → /peios/security-fundamentals
│ │ ├── trail.toml required: title, description
│ │ ├── 1--identity.topic/ a topic → /peios/security-fundamentals/identity
│ │ │ ├── trail.toml optional: title, inline_ref
│ │ │ ├── 100--sids.md an article → …/identity/sids
│ │ │ ├── 200--principals.md
│ │ │ ├── 300--tokens/ a subfolder → …/identity/tokens/…
│ │ │ │ ├── trail.toml optional
│ │ │ │ └── 100--issuing.md → …/identity/tokens/issuing
│ │ │ └── diagram.svg an image, published beside its article
│ │ └── 2--pgss.book/ a book → /peios/security-fundamentals/pgss
│ │ ├── trail.toml required: title, description; optional: short
│ │ ├── 1--scope.md §1 → …/pgss/scope
│ │ ├── 2--model/ a chapter, §2
│ │ │ ├── trail.toml optional
│ │ │ └── 1--objects.md §2.1
│ │ └── a1--glossary.md Appendix A
│ └── 2--tooling.shelf/ a shelf — a heading, not a URL segment
│ └── 1--pekit.topic/ → /peios/pekit (the shelf adds nothing)
│
└── pekit.product/ another product → /pekit
```
Everything below the root is optional. A site with one product, one topic and one article is a complete site; this site's `trail.product` is exactly that shape, four levels shallower than `peios.product`.
## The naming grammar
Three name shapes appear throughout the tree.
| Shape | Example | Where |
|---|---|---|
| `.product` | `pekit.product` | Only at the site root. |
| `--.` | `2--writing.topic` | Anthologies, topics, books, shelves. |
| `--` | `300--tokens`, `2--model` | Topic subfolders and book chapters — no suffix. |
| `--.md` | `100--sids.md` | Articles. |
| `--.link` | `3--faq.link` | Aliases; see [Link aliases](/trail/structuring-a-site/link-aliases.md). |
The parts:
- **``** is a non-negative integer used only for sorting among siblings. It never appears in a URL or a title. Gaps are fine and normal — numbering articles `100`, `200`, `300` leaves room to insert. Two siblings sharing an order is an error, because the resulting page order would depend on nothing you can see.
- **``** is lowercase kebab-case: ASCII lowercase letters, digits and hyphens, not starting or ending with a hyphen. It becomes the URL segment, and it is what you write in a `~link`.
- **``** is `antho`, `topic`, `book` or `shelf`.
Inside books, an order may also be written `a--` (`a1--glossary.md`). Those are **appendices**: lettered `A`, `B`, `C` instead of numbered, and sorted after every numbered sibling at their level. See [Books](/trail/structuring-a-site/books.md).
## URLs
A page's URL is its product slug followed by the slug of every container between the product and the page — with two exceptions.
```text
peios.product/1--security-fundamentals.antho/1--identity.topic/100--sids.md
→ /peios/security-fundamentals/identity/sids
```
The exceptions:
- **A shelf contributes no segment.** It is a heading on its parent's page, nothing more. A topic inside `2--tooling.shelf/` lives at `/peios/`, exactly as if the shelf were not there.
- **Order prefixes contribute nothing.** `1--identity.topic` gives the segment `identity`.
Which containers have a page of their own is worth knowing, because it decides what you can link to:
| | Has a page | Links to it land on |
|---|---|---|
| Site | `/` | — |
| Product | `/pekit` | its own landing page |
| Anthology | `/peios/security-fundamentals` | its own landing page |
| Book | `/peios/…/pgss` (the cover) | the cover |
| Article | its own URL | itself |
| Topic | no page | *(topics are not link targets)* |
| Topic subfolder | no page | *(not a link target, except from a `.link`)* |
| Book chapter | no page | *(not a link target)* |
| Shelf | no page | *(not a link target)* |
Topics, subfolders and chapters are real structure — they appear in sidebars, cards and contents lists, and links from those surfaces open their first article — but they have no page you can address, so a `~link` cannot point at one. Point at the article you actually mean.
## Titles
Titles come from three places, in order of precedence:
1. **An article's `title:` frontmatter**, which is required.
2. **A container's `trail.toml`**, where the `title` key is required for products, anthologies and books, and optional for topics, subfolders, chapters and shelves.
3. **The slug**, hyphens to spaces and each word capitalised: `the-two-gates` becomes "The Two Gates".
The derived form is good enough surprisingly often; write a `trail.toml` when it is not — acronyms and casing it cannot guess ("Peiso", "The Console"), or when the container needs `inline_ref` phrases.
## What may sit where
Trail rejects anything it does not recognise, so it is worth knowing what each level tolerates.
| Directory | May contain |
|---|---|
| The site root | `trail.toml`, `*.product/`, the output directory, files named by the config |
| A product | `trail.toml`, `.antho/`, `.topic/`, `.book/`, `.shelf/` |
| An anthology | `trail.toml`, `.antho/`, `.topic/`, `.book/`, `.shelf/` |
| A shelf | `trail.toml`, the same as its parent minus shelves — a shelf never holds a shelf |
| A topic | `trail.toml`, `.md` articles, `--/` subfolders, `.link` files, images |
| A topic subfolder | `trail.toml`, `.md` articles, `.link` files, images |
| A book | `trail.toml`, `.md` articles, `--/` chapters, `.link` files, images |
| A book chapter | `trail.toml`, `.md` articles, `--/` chapters, `.link` files, images |
Only the article-holding levels take files: `.md` articles, `.link` aliases and images may sit in a topic, a subfolder, a book or a chapter, and nowhere else. A product, anthology or shelf directory holds `trail.toml` and subdirectories, full stop.
Images sit beside the articles that use them and are published at the URL of the directory they were found in; see [Images](/trail/writing/images.md).
Two slugs are reserved: `print` (every container publishes a `/print` page) may not be an article slug, and `assets` and `pagefind` may not be product slugs.
## Ordering
Siblings sort by their `` prefix, ascending. Within a book, appendix entries (`a--`) sort after every numbered entry at the same level, and they are lettered rather than numbered.
Products are the exception: they have no order prefix. They sort by the root config's `featured` list first, in that list's order, then everything else by title.
## Where to go next
- [Products](/trail/structuring-a-site/products.md) — the product level in depth, and when to add another one.
- [Anthologies and shelves](/trail/structuring-a-site/anthologies-and-shelves.md) — grouping a large product.
- [Topics and folders](/trail/structuring-a-site/topics-and-folders.md) — the everyday container.
- [Books](/trail/structuring-a-site/books.md) — numbered, ordered documents with chapters and appendices.
---
# Products
_Trail / Structuring a site_
> A product is the top-level division of a trail site — a documented thing with its own landing page, colour, monogram and URL prefix. What goes in one, what its trail.toml needs, and how products are ordered.
A **product** is the outermost division of a trail site: one documented thing, with its own landing page, its own colour, and its own URL prefix. Products are the only children the site root will accept, so every page in the site belongs to exactly one.
On this site, `pekit`, `provium` and `trail` are products. So is `peios` itself — products are not necessarily software packages, they are simply the largest chunk of documentation a reader would think of as one subject.
## The directory
A product is a directory named `.product` at the site root. It has no order prefix.
```text
learn/
├── trail.toml
├── pekit.product/ → /pekit
└── trail.product/ → /trail
```
The slug becomes the URL prefix (`/pekit`) and the first segment of every [`~link`](/trail/writing/links-and-references.md) into that product. It must be lowercase kebab-case, and it may not be `assets` or `pagefind` — those collide with the output directories trail writes.
## The config
Every product needs a `trail.toml`, and all four keys are required:
```toml
# pekit.product/trail.toml
title = "pekit"
monogram = "pk"
color = "#22c55e"
description = "The recipe-driven build and packaging tool — declarative recipes in; built, tested, packaged software out."
```
| Key | |
|---|---|
| `title` | The product's display name, used everywhere the product is named. Unlike other containers, this is not derived from the slug — a product always states it. |
| `monogram` | A very short string — usually two characters — shown on the product's tile, on the front-page card and at the top of the product page. Initials or a shortened name. |
| `color` | A `#rrggbb` hex colour. Any other form is a build error. |
| `description` | One sentence, shown on the front-page card, under the product's name on its own page, and in `llms.txt`. It is also the product page's meta description. |
One optional key, `inline_ref`, claims phrases that auto-link to the product page wherever they appear in prose; see [Inline references](/trail/writing/inline-references.md).
## What the colour does
`color` is the product's accent, and by default it displaces the site accent on every page belonging to that product: card borders and hover states, the tile, sidebar highlights, heading numbers, RFC-2119 keywords, focus rings.
Setting `product_theming = false` in the root `trail.toml` turns this off site-wide, and everything tints from the site accent instead. Products still keep their monogram and card, they just stop colouring their pages. See [Theming](/trail/building/theming.md).
## What a product contains
A product directory holds its `trail.toml` and nothing but grouping directories:
- [**Anthologies**](/trail/structuring-a-site/anthologies-and-shelves.md) (`.antho`) — a titled landing page with its own children, for products big enough to need a second level.
- [**Topics**](/trail/structuring-a-site/topics-and-folders.md) (`.topic`) — a set of articles read in any order. The everyday container.
- [**Books**](/trail/structuring-a-site/books.md) (`.book`) — a formal, ordered document with a cover page, numbered sections and appendices.
- [**Shelves**](/trail/structuring-a-site/anthologies-and-shelves.md) (`.shelf`) — a titled heading grouping some of the above on the product page. No URL segment of its own.
Articles, images and `.link` files may **not** sit directly in a product directory; they live inside topics and books. A product with nothing in it is legal and simply renders an empty landing page.
Small products go straight to topics:
```text
pekit.product/
├── trail.toml
├── 1--getting-started.topic/
├── 2--recipes.topic/
├── 3--running.topic/
└── 4--reference.topic/
```
Large ones add a layer:
```text
peios.product/
├── trail.toml
├── 1--security-fundamentals.antho/
├── 2--using-peios.antho/
├── 3--advanced-peios.antho/
├── 4--developing-for-peios.antho/
└── 5--peiso.antho/
```
Both shapes are ordinary. Reach for an anthology when a product's topic list has grown long enough that readers have to hunt through it.
## The product page
Every product gets a landing page at `/`, built from the config and its children:
- A hero with the monogram tile, the title and the description.
- A "Documentation" section listing every child as a card. Anthologies and books get a card with their description; topics get a card listing their articles — all of them when there are four or fewer, otherwise the first three and a "See all N articles" link — with a count and the topic's total reading time.
- Each shelf becomes a subheading above its own row of cards. Runs of items outside any shelf render as an untitled row, in place.
## Ordering
Products have no order prefix. They sort by the root `trail.toml`'s `featured` list — in that list's order — and then everything not listed, by title.
```toml
# learn/trail.toml
featured = ["peios", "pekit", "provium", "universal-directory", "trail"]
```
That list does more than sort. **The front page shows only featured products.** An unfeatured product is still built, still searchable, still linkable, and still in the header's products menu — it just does not get a card on the front page. Naming a product that does not exist in `featured` is a build error.
## Roll-ups
A product totals up what is beneath it. Its reading time is the sum of every article's, and its `updated` date is the most recent `updated:` in the whole product. Anthologies, topics, books and chapters do the same at their own level. See [Articles and frontmatter](/trail/writing/articles-and-frontmatter.md).
## When to add a product
A product is a heavy division: its own colour, its own landing page, its own URL prefix, and a separate card on the front page. Add one when readers would go looking for the subject by name and would not expect to find it filed under something else.
Within a single product, the lighter divisions — anthologies for a second level of landing pages, shelves for a heading, topics for a set of articles — are almost always the better answer.
---
# Anthologies and shelves
_Trail / Structuring a site_
> Two ways to group a product's contents — an anthology is a second landing page with its own URL, a shelf is a heading on the page above it. When to reach for each, and how deep they nest.
Once a product has more than a handful of topics, its landing page becomes a wall of cards. Trail offers two ways to break that up, and the difference between them is exactly one thing: **whether the grouping gets a page of its own**.
| | URL segment | Page | Sidebar | Nests |
|---|---|---|---|---|
| **Anthology** (`.antho`) | yes | its own landing page | — | in products and anthologies |
| **Shelf** (`.shelf`) | no | no — a heading on its parent's page | — | in products and anthologies, never in a shelf |
Reach for a shelf when the topics belong together but readers should still see them all at once. Reach for an anthology when the group is big enough to deserve its own front door.
## Anthologies
An anthology is a directory named `--.antho`. It has a landing page at its own URL, listing everything inside it exactly as a product page lists its own children.
```text
peios.product/
├── trail.toml
├── 1--security-fundamentals.antho/ → /peios/security-fundamentals
│ ├── trail.toml
│ ├── 1--identity.topic/ → /peios/security-fundamentals/identity
│ └── 2--pgss.book/ → /peios/security-fundamentals/pgss
└── 2--using-peios.antho/ → /peios/using-peios
```
Its `trail.toml` requires two keys:
```toml
# 1--security-fundamentals.antho/trail.toml
title = "Security fundamentals"
description = "How Peios decides who may do what: identity, tokens, and the two gates every request passes."
```
`title` is the heading and the breadcrumb; `description` is the standfirst on the page, the text on the card that links to it from the product page, and the entry in `llms.txt`. The optional `inline_ref` key claims phrases pointing at this anthology's page; see [Inline references](/trail/writing/inline-references.md).
An anthology may contain anthologies, topics, books and shelves — the same set a product may contain. Anthologies nesting inside anthologies is legal and unbounded, and each level adds a URL segment:
```text
/peios/developing-for-peios/apis/filesystem/open
└─ anthology ──────┘ └ antho ┘ └ topic ─┘ └ article
```
In practice two levels is plenty. Deeper than that and readers stop being able to guess where anything lives.
### The anthology page
The page mirrors a product page one level down: a breadcrumb trail back to the product (and through any parent anthologies), the title, the description, and a "Topics" section of cards. Nested anthologies and books get a description card; topics get a card listing their articles.
## Shelves
A shelf is a directory named `--.shelf`. It is presentation only: **a shelf contributes no URL segment, has no page, and never appears in a breadcrumb.** Its whole job is to put a subheading above a row of cards on the page it sits in.
```text
peios.product/
└── 3--tooling.shelf/ (no URL of its own)
├── trail.toml
├── 1--pekit.topic/ → /peios/pekit
└── 2--provium.topic/ → /peios/provium
```
Note the URLs: the topics live directly under the product, exactly as they would if the shelf directory were not there.
Its `trail.toml` is optional and carries at most a title:
```toml
# 3--tooling.shelf/trail.toml
title = "Tooling"
```
Without one, the title is derived from the slug — `3--tooling.shelf` becomes "Tooling" anyway, so most shelves need no config at all. A shelf may **not** declare `inline_ref`: it has no page to link to, so the phrase would have nowhere to land. Declare it on the shelf's items instead.
### How shelves render
On the parent's page, children render in order. A run of items outside any shelf renders as an untitled row of cards; each shelf renders as its title followed by its own row:
```text
Documentation
[ Getting started ] [ Concepts ] ← loose items, no heading
Tooling ← shelf title
[ pekit ] [ provium ]
Specifications ← another shelf
[ PGSS ] [ PCDS ]
```
Because a shelf's items share their parent's URL space, their slugs must be unique across the whole parent — two shelves cannot both contain a `getting-started` topic, since both would want `/peios/getting-started`. Trail rejects that at build time.
### The rules
- A shelf may sit in a product or an anthology.
- A shelf may contain anthologies, topics and books.
- **A shelf may never contain another shelf.** Nested headings on a card grid are not a structure worth having; if you need the second level, use an anthology.
- A shelf directory holds `trail.toml` and subdirectories only — no articles, no images.
## Choosing
Start flat. A product with four or five topics needs neither of these.
When the list gets long, ask whether the groups are worth a page. "Tooling" as a heading over two topic cards is a shelf. "Security fundamentals" — nine topics, two specifications, and a description worth reading — is an anthology.
The cost of an anthology is a URL segment on every page beneath it and one more click for the reader. The cost of a shelf is nothing at all, which is why it is usually the right first move.
---
# Topics and folders
_Trail / Structuring a site_
> The topic is trail's everyday container — a set of articles read in any order, with an optional single level of subfolders. Where the sidebar comes from, why a topic has no page, and where links to one land.
A **topic** is a set of articles on one subject, read in any order. It is the container most pages live in, and the one to reach for unless you specifically need a [book](/trail/structuring-a-site/books.md).
"Getting started", "Concepts", "Configuration", "Reference" — those are topics. The reader arrives at one of the articles from search or a link, reads it, and moves on; the sidebar is there for when they want to see what else is nearby.
## The directory
A topic is a directory named `--.topic`, sitting in a product, an anthology or a shelf. Its articles are the `.md` files inside it:
```text
4--reference.topic/ (the topic; no page of its own)
├── trail.toml optional
├── 100--recipe-format.md → /pekit/reference/recipe-format
├── 200--supporting-files.md → /pekit/reference/supporting-files
└── 300--cli.md → /pekit/reference/cli
```
The `4` orders this topic among its siblings; `reference` is the URL segment. Articles carry the same `--` grammar, and their order prefixes decide reading order — the sidebar, the previous/next links, and the order they appear in the topic's single-page view.
Numbering in hundreds is the convention across this site. It is not a rule — `1--`, `2--`, `3--` works identically — but it means you can insert `150--` between two articles without renaming anything.
## The config
A topic's `trail.toml` is optional, and holds at most two keys:
```toml
# 4--reference.topic/trail.toml
title = "Reference"
```
Without it, the title is derived from the slug: `4--reference.topic` becomes "Reference", `2--writing-tests.topic` becomes "Writing tests". Write the file when that derivation is wrong — an acronym, a proper noun, unusual casing — or when the topic needs `inline_ref` phrases, which claim text that should auto-link to the topic's first article. See [Inline references](/trail/writing/inline-references.md).
## A topic has no page
This is the one surprising thing about topics. There is no page at `/pekit/reference` — the topic is not a destination, it is a grouping.
That has three consequences:
- **A topic appears as a card** on its product's or anthology's page, listing its articles (all of them when there are four or fewer, otherwise the first three plus a "See all" link) with a count and its total reading time.
- **Links land on the first article.** Every surface that shows a topic — its card heading, its "See all" link, the sidebar heading on an article page — points at the topic's first article in reading order.
- **A topic is not a `~link` target.** `~pekit/reference` resolves nothing, because `reference` is not the last segment of any page's path. Link to the article you mean: `~pekit/reference/cli`.
What *does* exist at the topic's path is its single-page view: `/pekit/reference/print` renders every article in the topic as one long page, and `/pekit/reference/print.md` is the same thing as markdown. See [The output surface](/trail/building/the-output-surface.md).
## Subfolders
A topic that has grown past a comfortable sidebar can group runs of articles into **subfolders** — plain `--` directories, with no type suffix:
```text
2--concepts.topic/
├── 100--objects-and-identity.md → /ud/concepts/objects-and-identity
├── 200--the-schema-model.md → /ud/concepts/the-schema-model
└── 300--replication/ a subfolder
├── trail.toml optional
├── 100--topology.md → /ud/concepts/replication/topology
└── 200--conflicts.md → /ud/concepts/replication/conflicts
```
A subfolder:
- **adds a URL segment**, unlike a shelf;
- **has no page of its own**, like a topic — links from the sidebar open its first article;
- **renders as a collapsible group in the sidebar**, expanded automatically when the article being read is inside it;
- **may hold `trail.toml`, articles, `.link` files and images — but not another subfolder.** Subfolders are exactly one level deep. A topic needing more nesting than that is either two topics or a book.
Its optional `trail.toml` takes the same `title` and `inline_ref` keys a topic's does, and its title derives from its slug the same way.
An empty subfolder is tolerated and simply not shown, so you can create the directory before its articles exist.
## The sidebar
On an article page, the sidebar shows the article's own topic: the topic title (linking to its first article) above the topic's contents in reading order, with subfolders as collapsible groups and the current article marked. It shows one topic — not the whole product — because the topic is the unit a reader is working within.
Below it, "On this page" lists the article's own `h2` and `h3` headings, and highlights the one currently in view.
## Reading order and the pager
The prev/next links at the foot of an article step through the whole topic in reading order, subfolder contents flattened in place. The last article of one topic does not lead to the first of the next; the pager is a topic-local device.
## Topic or book?
| Use a topic when | Use a book when |
|---|---|
| Articles can be read in any order | The document is read in order, or cited by section |
| No page needs to say "§2.4" | Sections need stable numbers |
| Grouping is for navigation | The whole thing is one document with a cover |
| One level of subfolders is enough | Nesting goes deeper than two levels |
Almost all documentation is topics. Books are for specifications, formal references and manuals — see [Books](/trail/structuring-a-site/books.md).
---
# Books
_Trail / Structuring a site_
> A book is a formal, ordered document — a specification or manual — with a cover page, dotted section numbers derived from directory names, chapters nesting to any depth, and lettered appendices.
A **book** is a document read in order and cited by section: a specification, a formal reference, a manual. Where a [topic](/trail/structuring-a-site/topics-and-folders.md) is a set of related pages, a book is one document that happens to be split across pages.
Books get three things topics do not: a cover page, stable section numbers derived from the directory structure, and appendices.
## The directory
A book is a directory named `--.book`, sitting in a product, an anthology or a shelf:
```text
1--pgss.book/ → /demo/pgss (the cover)
├── trail.toml
├── 1--introduction.md §1 → /demo/pgss/introduction
├── 2--logon/ §2 a chapter
│ ├── trail.toml
│ ├── 1--overview.md §2.1 → /demo/pgss/logon/overview
│ └── 2--flow.md §2.2
└── a1--references.md Appendix A
```
Its `trail.toml` requires a title and a description:
```toml
# 1--pgss.book/trail.toml
title = "Peios Generic System Standards"
short = "PGSS"
description = "Cross-platform system standards from the Peios Project"
```
| Key | |
|---|---|
| `title` | Required. The full name, shown on the cover and in cards. |
| `description` | Required. The standfirst on the cover, the card text, and the `llms.txt` entry. |
| `short` | Optional. An abbreviation — usually an acronym — used where the full title will not fit: the sidebar heading, the pill on the book's card, and the line above the title on the cover. |
| `inline_ref` | Optional. Phrases that auto-link to this book, and which may carry a `§` section suffix in prose. See [Inline references](/trail/writing/inline-references.md). |
## Section numbers come from the directory names
This is the part worth reading twice. **A book's section numbers are its order prefixes**, joined with dots along the path from the book root:
```text
2--logon/ → §2
1--overview.md → §2.1
3--errors/ → §2.3
1--codes.md → §2.3.1
```
Two consequences follow:
- **Number books from 1, not 100.** The hundreds convention used for [topic articles](/trail/structuring-a-site/topics-and-folders.md) would produce §100 and §200. In a book the prefix is the published section number, so `1--`, `2--`, `3--` is what you want.
- **Gaps show through, on purpose.** If `2--` is deleted the book goes §1, §3 — because in a specification, section numbers are addresses. Renumbering to close a gap silently invalidates every citation anyone has ever written; leaving the gap is the honest outcome. Renumber deliberately, or not at all.
Inside an article, `h2` and `h3` headings continue the numbering as real text: in §2.1, the first `h2` is §2.1.1 and its first `h3` is §2.1.1.1. Headings deeper than `h3` are not numbered. The numbers are rendered into the heading itself rather than drawn with CSS counters, so they can be searched, selected and copied.
## Chapters
A chapter is a plain `--` directory — no type suffix, exactly like a [topic subfolder](/trail/structuring-a-site/topics-and-folders.md) — except that chapters may nest as deeply as the document needs.
A chapter:
- **contributes a URL segment and a section number**;
- **has no page of its own** — links to it open its first article;
- **must contain at least one article, somewhere beneath it.** An empty chapter is a build error, because it would appear in the contents as a number leading nowhere;
- takes an optional `trail.toml` with `title` and `inline_ref`, with the title otherwise derived from the slug.
## Appendices
An entry whose order is written `a--` is an **appendix**: lettered instead of numbered, and sorted after every numbered sibling at its level.
```text
1--pgss.book/
├── 1--introduction.md §1
├── 2--logon/ §2
├── a1--references.md Appendix A
└── a2--glossary/ Appendix B
└── 1--terms.md §B.1
```
- Letters run `A`, `B`, … `Z`, `AA`, `AB`, and so on.
- The numbering is by `a` order, not position: `a1--` is A, `a2--` is B. Appendix numbering starts at `a1`; `a0--` is an error.
- Appendices work at **any** level, not just the book root. An appendix chapter inside a numbered chapter gives §2.A, and its articles §2.A.1.
- Where the entry itself is displayed — the sidebar, the contents — it is labelled "Appendix A" in full. In section references it is just the letter.
## The cover page
A book's URL is its cover: the product and anthology breadcrumbs, the `short` name if it has one, the title, the description, and the book's total reading time and last-updated date. The contents are the sidebar tree beside it — the whole book, chapters as collapsible groups, section numbers on every entry.
The tree remembers which chapters you opened, per book, as you move between pages.
## Frontmatter is different inside a book
Book articles use a reduced frontmatter set. `title:` is still required; `description:`, `related:`, `inline_ref:`, `updated:` and `reading_minutes:` all still work.
**`type:` is an error inside a book.** The concept/how-to/reference taxonomy describes how to approach a page, and inside a formal document that question is already answered — you read it in order. Trail rejects the key rather than letting it sit there meaning nothing.
## Citing sections
Books are the reason [inline references](/trail/writing/inline-references.md) exist. A book that claims a phrase can be cited by section from anywhere in the site:
```markdown
Every token MUST carry a lifetime, per PGSS §2.1.
```
"PGSS" links to the book; "PGSS §2.1" links to the exact section, resolving through the book's index of section numbers — including numbers that belong to a heading inside an article, not just to the article itself. Within a book's own pages, a bare `§2.1` resolves the same way against the surrounding book.
Because a section number is an address, this is where the "gaps show through" rule earns its keep.
## When a book is the wrong answer
A book is a commitment: numbered sections that readers may cite, an order that means something, and a cover page. Most documentation is not that. If your sections would never be cited by number, and the pages can be read in any order, you want a topic.
---
# Link aliases
_Trail / Structuring a site_
> A .link file places an existing page in a second location — same content, second URL, canonical pointing home. How to write one, what it may target, and why the alias stays out of the search index.
Some pages belong in two places. A "Signing and provenance" article that lives in pekit's *Running* topic is also the page a reader of the security anthology goes looking for; a specification's terminology section is also an appendix of the manual next to it.
A **`.link` file** places an existing page at a second location. The content is not copied — it is the same article, rendered again at a second URL, with its canonical URL still pointing at the original.
## Writing one
A link is a file named `--.link`, holding TOML:
```toml
# 3--signing.link
target = "~pekit/running/signing-and-provenance"
title = "Signing and provenance"
```
| Key | |
|---|---|
| `target` | Required. A [`~` page reference](/trail/writing/links-and-references.md), in exactly the grammar body links use. It must start with `~`. |
| `title` | Optional. The title the aliased page carries *here*. Without it, the title is derived from the link's own slug. |
The `--` prefix works exactly as it does for an article: the order places the alias among its siblings, and the slug becomes its URL segment. The alias does not inherit the target's slug, its order, or its title — it is a new entry in a new place that happens to render the target's body.
## Where a link may live
`.link` files sit wherever articles sit: in a topic, in a topic subfolder, in a book, or in a book chapter. They may not sit in a product, an anthology or a shelf.
What each may target:
| In a | May target |
|---|---|
| Topic | an article, **or a whole topic subfolder** |
| Topic subfolder | an article |
| Book or chapter | an article |
Aliasing a subfolder from a topic clones the entire folder into that topic's URL space — every article in it becomes an alias of its own original, under the new folder's slug. It is the one case where a single link file produces more than one page.
A link may never target another link. That would make the canonical chain ambiguous, so trail rejects it.
## What the alias page is
The aliased page renders exactly like the original: same body, same images, same headings. What differs:
- **Its URL and title** are the link's, not the target's.
- **Its canonical URL is the original's.** Search engines are told which of the two URLs is the real one, so the duplicate does not compete with it.
- **It is not in the search index.** Searching finds the original; the alias exists for people navigating the tree.
- **It claims no `inline_ref` phrases.** The original keeps them — a phrase must have exactly one destination.
- **"Edit this page" points at the original's source file**, because that is the file to edit.
- Inside a book, an alias gets a section number from its own order prefix like any other entry, may be an appendix (`a--`), and carries no `type:` or `description:` — book entries never do.
## Example
Pekit's signing article lives in its *Running* topic. The security anthology wants it too:
```text
pekit.product/3--running.topic/
└── 600--signing-and-provenance.md → /pekit/running/signing-and-provenance
peios.product/1--security-fundamentals.antho/4--supply-chain.topic/
├── 100--overview.md
└── 200--pekit-signing.link → /peios/security-fundamentals/supply-chain/pekit-signing
```
```toml
# 200--pekit-signing.link
target = "~pekit/running/signing-and-provenance"
title = "Signing in pekit"
```
Both URLs work. Both show the same prose. Search returns the pekit one. Editing either takes you to the same source file.
## When not to use one
An alias is right when one piece of writing genuinely belongs in two navigational places. It is the wrong tool for:
- **A cross-reference.** If you just want to point at another page, write a [`~link`](/trail/writing/links-and-references.md) in the prose, or add it to the article's `related:` list.
- **A page that should differ between the two locations.** An alias is the same article; there is no way to vary it. Write two articles.
- **A rename.** Aliases are not redirects — the old URL still has to exist as a `.link` file forever. If a page has moved for good, move it and fix the links; trail will tell you which ones broke.
---
# Articles and frontmatter
_Trail / Writing_
> Every frontmatter key an article may carry — title, type, description, related, inline_ref, updated and reading_minutes — what each one actually does, and how reading times and dates roll up the tree.
An article is a single `.md` file named `--.md`: a YAML frontmatter block, then markdown.
```markdown
---
title: Quick start
type: how-to
description: Build and package a tiny "hello" program with pekit, from an empty directory.
related:
- pekit/getting-started/what-is-pekit
- pekit/recipes/anatomy
---
This page takes you from an empty directory to a working `.peipkg`…
```
The frontmatter is required and must be the first thing in the file: a line of exactly `---`, the YAML, and a closing `---`. A file that does not start with `---`, or whose block is never closed, is a build error. So is any key not listed below — a typo'd `descripton:` fails the build rather than silently doing nothing.
## The keys
| Key | Required | |
|---|---|---|
| `title` | yes | The page's name: its `h1`, its breadcrumb, its sidebar entry, its search-result heading, its `og:title`. |
| `type` | in topics | The learn taxonomy — `concept`, `how-to`, `reference` on this site. **An error inside a [book](/trail/structuring-a-site/books.md).** |
| `description` | no | One sentence. Becomes the page's meta description and social-preview text. |
| `related` | no | Page references shown as a "Related Content" list at the foot of the page. |
| `inline_ref` | no | Phrases that auto-link to this page wherever prose states them. |
| `updated` | no | An ISO `YYYY-MM-DD` date. |
| `reading_minutes` | no | Overrides the estimated reading time. |
### title
The only key every article must have, in topics and books alike. It is not derived from the slug — unlike a topic or chapter title, an article states its own.
### type
Required on every article in a topic, and rejected on every article in a book.
Trail does not constrain the value or display it on the page; it is carried through to `site.json` for tooling that wants to filter by it. What it is really for is the author: deciding whether a page is a **concept** (explaining how something works), a **how-to** (walking through a task) or a **reference** (exhaustive, looked-up rather than read) is a genuinely useful discipline, and pages that cannot answer the question are usually two pages.
Inside a book the question is already answered — a specification is read in order — so trail rejects the key rather than let it sit there meaning nothing.
### description
Optional, but write one. It becomes:
- the page's `` and `og:description`, which is what search engines and chat apps show;
- the standfirst line in the page's [markdown mirror](/trail/building/the-output-surface.md);
- the `description` field in `site.json`.
It is not displayed on the page itself, and it is not the in-site search snippet — Pagefind builds those from the body text around the match.
Build with [`--strict`](/trail/reference/cli.md) to make a missing description a build failure. Alias pages are exempt, since the original carries it.
### related
A list of page references, in the same grammar body links use but **without** the leading `~`:
```yaml
related:
- pekit/running/invocation
- peios/package-management/overview
```
They render as a "Related Content" list under the article, and they appear in the page's markdown mirror and in `site.json`. Resolution is as strict as a body link: an ambiguous reference always fails the build, and a missing one fails unless `--allow-dangling-links` is set, in which case it warns and drops from the list.
### inline_ref
Phrases that should become links to this article wherever they appear in the site's prose:
```yaml
inline_ref:
- PCDS GUID
- PCDS GUIDs
```
Every occurrence in ordinary prose, anywhere on the site, links here — except on this page itself. Phrases are claimed site-wide and exclusively; two pages claiming the same phrase is a build error. See [Inline references](/trail/writing/inline-references.md).
### updated
An ISO date, and validated as one — `2026-05-01`, not `May 2026` and not `01/05/2026`.
```yaml
updated: 2026-05-01
```
It shows in the page's meta line, and it becomes the page's `` in `sitemap.xml`. It is deliberately manual: file modification times are noise (a whitespace fix is not an update, and a checkout rewrites them all), and trail does not read git history. An article with no `updated:` simply does not show one.
### reading_minutes
Trail estimates reading time from the body's word count at 200 words a minute, rounded up, with a floor of one minute. Code blocks count — they are read, just differently.
Set `reading_minutes:` when the estimate is wrong: a dense reference table reads far slower than its word count suggests, and a page that is mostly a long code listing far faster.
```yaml
reading_minutes: 30
```
## Roll-ups
Reading times and dates add up the tree. A subfolder totals its articles; a topic totals its articles and subfolders; a book totals its chapters; an anthology totals its topics and books; a product totals everything in it.
- **Reading time** is the sum, so a book's cover can say how long the whole book takes and a topic card can say how long the topic is.
- **`updated`** is the *most recent* date anywhere beneath, so a container reflects its freshest page.
Roll-ups are computed after `.link` aliases are resolved, so an aliased article counts in the totals of the place it was linked into.
## The body
Everything after the closing `---` is [CommonMark](https://commonmark.org) with GitHub extensions: tables, strikethrough, footnotes, and `> [!NOTE]`-style [admonitions](/trail/writing/admonitions-tabs-and-diagrams.md). On top of that, trail adds:
- [`~page` references](/trail/writing/links-and-references.md) — link by page identity instead of URL.
- [Co-located images](/trail/writing/images.md) — `` beside the article, with dimensions filled in and captions turned into figures.
- [Syntax-highlighted code blocks](/trail/writing/code-blocks.md) with copy buttons.
- [Tab groups and mermaid diagrams](/trail/writing/admonitions-tabs-and-diagrams.md).
- [Inline references, `§` section citations and RFC-2119 keyword highlighting](/trail/writing/inline-references.md).
A few things happen to headings automatically: `h2` and `h3` become the "On this page" list, every heading gets a stable id and a permalink anchor, and inside a book they carry their section numbers as real text. Ids come from the heading text, with a numeric suffix if two headings on a page would otherwise collide.
Tables are wrapped in their own horizontally-scrolling container, so a wide table never makes the whole page scroll sideways.
## Naming and ordering
The filename is not decoration:
```text
200--quick-start.md
│ └── the URL segment, and what you write in a ~link
└── the sort key among siblings — never shown, never in a URL
```
Two files sharing an order in the same directory is an error. Numbering in hundreds leaves room to insert later; inside a [book](/trail/structuring-a-site/books.md) the prefix is the published section number, so number from 1 there instead.
`print` is a reserved slug — every container publishes a `/print` page — so `100--print.md` is rejected.
---
# Links and references
_Trail / Writing_
> The ~ reference grammar — link to a page by its identity rather than its URL, with the shortest unambiguous suffix. How resolution works, what can be a target, and what the build does when a link breaks.
Trail links pages by **identity**, not by URL. Instead of writing a path that breaks the moment a page moves, you write a `~` reference naming the product and enough of the page's slugs to be unambiguous:
```markdown
See [Commands and targets](~pekit/running/commands-and-targets) first.
```
Reorganise the tree — move that topic into an anthology, wrap it in a shelf, renumber it — and the link still resolves. Delete the target, and the build fails and tells you every page that pointed at it.
## The grammar
```text
~[/]…[#]
```
- The **first segment is always a product slug**. There is no relative form and no site-wide search; every reference says which product it means.
- The **remaining segments match the end of a page's path.** Trail compares them against each page's slugs — the anthology slugs, the topic slug, any subfolder or chapter slugs, and the page's own — and matches if your segments are the tail of that list.
- Exactly one page must match. Zero or several is an error.
- A **fragment** may follow, and is appended to the resolved URL: `~pekit/reference/cli#global-flags`.
The rule of thumb is: **write the shortest thing that is unambiguous**, and add segments from the left only when you have to.
### A worked example
Given this page:
```text
/peios/security-fundamentals/identity/tokens/issuing
└ anthology ───────┘ └ topic ┘ └folder┘ └page┘
```
all of these resolve to it:
```text
~peios/issuing
~peios/tokens/issuing
~peios/identity/tokens/issuing
~peios/security-fundamentals/identity/tokens/issuing
```
`~peios/issuing` is the one to write — until a second page in `peios` is also called `issuing`, at which point that reference becomes ambiguous, the build fails, and you add a segment.
Note that the deeper segments are for *disambiguation only*. A chapter or subfolder slug can appear in a reference even though it is not a page you could link to on its own.
## What can be a target
| | Targetable | Reference |
|---|---|---|
| A product | yes | `~pekit` |
| An anthology | yes | `~peios/security-fundamentals` |
| A book cover | yes | `~peios/pgss` |
| An article | yes | `~pekit/reference/cli` |
| A topic | **no** | link to an article in it |
| A topic subfolder | **no** | *(except as a `.link` target)* |
| A book chapter | **no** | link to an article in it |
| A shelf | **no** | it has no page at all |
Topics, subfolders and chapters have no page of their own, so there is nothing for a reference to land on. Link to the article you actually mean.
## Ordinary links still work
A `~` at the start of a destination is what makes it a reference. Everything else is left alone:
```markdown
[the CommonMark spec](https://spec.commonmark.org) external, untouched
[the sitemap](/sitemap.xml) root-relative, untouched
[this section](#the-grammar) same-page fragment
```
Root-relative links are the escape hatch for the handful of URLs that are not pages — `/print` views, `/llms.txt`, `/site.json`. They are not checked, so they are also the way to ship a broken link. Prefer `~` wherever the target is a page.
`~` is only meaningful in a *link* destination. In an [image](/trail/writing/images.md) destination it is an error, with a message saying so: images are files, addressed relative to the article.
## Where else references are used
The same grammar appears in three other places:
```yaml
# an article's frontmatter — no leading ~
related:
- pekit/running/invocation
```
```toml
# a .link alias file — with the ~
target = "~pekit/running/signing-and-provenance"
# the root trail.toml's nav — with the ~, or an external URL
[[nav]]
label = "Specs"
url = "~peios/pgss"
```
The `related:` list is the odd one out in dropping the `~`; everything else keeps it.
## When a link breaks
Every link in the site is checked on every build, and all the failures are reported together — one build tells you the whole story rather than stopping at the first bad reference.
```text
Error: 3 broken links:
in article '/pekit/recipes/anatomy': link '~pekit/running/invokation' matches no page in product 'pekit'
in article '/peios/identity/sids': link '~pekti/overview' names unknown product 'pekti'
in article '/pekit/reference/cli': link '~pekit/targets' is ambiguous; candidates:
~pekit/running/commands-and-targets/targets
~pekit/reference/recipe-format/targets
```
There are three failure kinds, and they are not treated alike:
| | Means | With `--allow-dangling-links` |
|---|---|---|
| **Unknown product** | the first segment is not a product slug | warning |
| **No match** | nothing in that product ends with those segments | warning |
| **Ambiguous** | two or more pages match | **still fatal** |
Ambiguity is never downgradable. A missing target is a link that does nothing; an ambiguous one is a link that goes somewhere *specific and possibly wrong*, and only the author knows which page was meant.
`--allow-dangling-links` is for the middle of a refactor, when you have moved a hundred pages and want to see the site before fixing every reference. It is not a setting to leave on.
## References in print views and mirrors
The [single-page and markdown views](/trail/building/the-output-surface.md) rewrite references so they still work away from the site:
- In a **`/print` bundle**, a reference to a page inside the same bundle becomes an in-document anchor, so the whole document navigates itself. A reference to a page outside it becomes an absolute URL when the site config has a `url`, and stays root-relative otherwise.
- In a **`.md` mirror**, a reference becomes the target's own `.md` URL, so a reader following links through the markdown surface stays in it.
---
# Images
_Trail / Writing_
> Images live beside the articles that use them and are referenced by relative path. Dimensions, captions and figures, what happens to an unreferenced file, and which formats trail recognises.
Images live **beside the articles that use them**. There is no assets directory to maintain and no separate URL scheme to remember: drop the file in the same folder as the `.md`, and reference it by name.
```text
2--logon.topic/
├── 100--overview.md
└── logon-flow.svg
```
```markdown
```
The image publishes at the URL of the directory it was found in, keeping its own file name — here `/peios/logon/logon-flow.svg`. Move the folder and the image moves with it.
## Referencing
Destinations resolve **relative to the article's own `.md` file**, exactly as an editor's markdown preview resolves them. Relative paths may climb out of a subfolder with `..`, so a diagram shared by a folder's worth of articles can sit one level up:
```text
2--concepts.topic/
├── shared-diagram.svg
└── 300--replication/
├── 100--topology.md 
└── 200--conflicts.md 
```
Three kinds of destination are left exactly as written and never checked: absolute URLs (`https://…`), root-relative paths (`/…`) and `data:` URIs.
A `~` reference in an image destination is a build error. `~` names pages, not files.
## Where images may sit
Anywhere articles may sit: a topic, a topic subfolder, a book, or a book chapter. Not in a product, anthology or shelf directory — those hold only `trail.toml` and subdirectories.
The file name must be a valid slug plus a **lowercase** extension: `logon-flow.svg`, not `Logon Flow.SVG`. Recognised extensions are:
```text
png jpg jpeg gif svg webp avif
```
Anything else in an article directory is an "unexpected file" error — which is the point. A `.pdf` or a `.xlsx` sitting in a content folder is almost always a mistake, and trail would rather say so than quietly ignore it.
## Dimensions
Trail reads each raster image's header at build time and emits real `width` and `height` attributes:
```html
```
The browser can then reserve the right space before the file arrives, so text does not jump around as images load. SVGs get no dimensions — they scale — and neither does any file whose header cannot be read.
## Captions and figures
An image with a **title** — the quoted string after the destination — that sits alone in its own paragraph becomes a `` with a ``:
```markdown
```
```html
How a logon token reaches the session service
```
The two strings do different jobs and should say different things. The **alt text** describes the image for someone who cannot see it. The **caption** is prose everyone reads, and can say what the diagram is *for*.
An image without a title, or one sharing its paragraph with other text, renders as an ordinary inline ``.
## Unreferenced images
Only images some article actually references are copied into the output. One that nothing references prints a warning and is left out:
```text
warning: image '/…/2--logon.topic/old-diagram.png' is not referenced by any article and was not published
```
A warning rather than an error, deliberately: adding the file before the article that will use it is a normal way to work. But a warning that stays warning is a file to delete.
A referenced image that does not exist is the other way round — a broken link, fatal unless `--allow-dangling-links` downgrades it:
```text
in article '/peios/logon/overview': image 'logon-flow.svg' not found (resolved relative to the article's folder)
```
## In the other views
Images work in the [markdown mirrors and `/print` bundles](/trail/building/the-output-surface.md) too: since those serve an article's body away from its own folder, relative destinations are rewritten to the image's published URL.
## Diagrams
For flowcharts, sequence diagrams and the like, consider a [mermaid code block](/trail/writing/admonitions-tabs-and-diagrams.md) instead of an image file. Mermaid diagrams are text — diffable, editable, and they follow the reader's light or dark theme, which a checked-in PNG cannot.
---
# Code blocks
_Trail / Writing_
> Fenced code blocks are highlighted at build time into themed classes, wrapped with a copy button, and labelled with their language. Which languages the bundled highlighter knows, and what happens to the ones it does not.
Fenced code blocks work as they do in any markdown, with an info string naming the language:
````markdown
```rust
fn main() {
println!("hello");
}
```
````
Trail highlights that at build time and wraps it with a copy button:
```html
fn …
```
## Highlighting is classes, not colours
Highlighting happens once, when the site is built — there is no highlighter shipped to the browser and no flash of unstyled code.
What is emitted is **class names**, not inline colours: `hl-keyword`, `hl-string`, `hl-comment` and so on, prefixed so they cannot collide with the theme's own classes. Those classes resolve through the same CSS custom properties as everything else on the page, which is why code follows the reader's light or dark choice instead of freezing one palette into the markup. [Theming](/trail/building/theming.md) covers the tokens involved.
## The copy button
Every code block gets one. It sits in the top-right corner, appears on hover (and is always visible on touch devices), copies the block's text to the clipboard, and briefly says so.
Nothing is stripped from what it copies, so a `$` prompt in a shell example is copied along with the command. Write shell examples without prompts if you would rather they paste cleanly.
## Which languages are highlighted
Trail bundles [syntect](https://github.com/trishume/syntect) as its highlighter, with the extended syntax collection from [`two-face`](https://codeberg.org/CosmicHarper/two-face) — the same definitions [bat](https://github.com/sharkdp/bat) ships, a little over two hundred of them. The info string is matched against a syntax's name or one of its file extensions, case-insensitively, so both `rust` and `rs` work.
Everything you are likely to reach for is covered:
```text
bash / sh / fish / zsh asm awk cmd / bat c / c++ / c#
clojure cmake coffeescript crystal css / scss / sass / less / stylus
d dart diff dockerfile dotenv elixir elm
erlang f# f90 gd gitconfig / gitignore
glsl go / gomod graphql dot groovy haskell hcl / terraform
html http idris ini java js jq
json / jsonnet julia kotlin latex / bibtex lean
lisp llvm lua make markdown matlab nginx
nim nix objective-c ocaml odin orgmode pascal
perl php protobuf puppet purescript python qml
r racket rego robot ruby / haml / slim rust
scala solidity sql svelte swift systemverilog / verilog / vhdl
tcl toml typescript / tsx typst vim vue
wgsl xml / svg yaml zig
```
…alongside the config and system formats that turn up in documentation: `crontab`, `fstab`, `passwd`, `resolv`, `syslog`, `ssh_config`, `known_hosts`, `.htaccess`, `requirements.txt`, `csv` / `tsv`, `manpage`, `strace`, `email`.
**Still absent:** `powershell`, and the shell-session forms (`console`, `shell-session`). A `console` block renders as plain text — which is usually what you want anyway, since a `$` prompt is not shell syntax.
An info string the set does not recognise is **not** an error and does not fail the build: the block renders as plain escaped code, with the same wrapper, the same copy button, and its language still recorded on it as `data-language`.
The definitions' licences ship with every build at `/assets/LICENSE-Syntaxes.txt`.
## Blocks with no language
A fence with no info string renders as escaped plain text, with the wrapper and copy button intact. Use one for output, trees and anything that is not a language:
````markdown
```
built 1227 pages (8 products) → ./dist
```
````
Across this site the convention is `text` for that. The highlighter does not recognise `text` as a language, so it renders identically to a bare fence while reading more explicitly in the source.
Indented code blocks (four spaces) are supported too, and are treated as having no language.
## Inline code
Inline `` `code` `` is ordinary markdown and is not highlighted. It is also excluded from [inline reference](/trail/writing/inline-references.md) matching: a claimed phrase inside backticks stays plain text, so writing `` `PCDS GUID` `` when you mean the literal string does not produce a link.
## In the other views
Code blocks survive into the [markdown mirrors and `/print` bundles](/trail/building/the-output-surface.md) as ordinary fenced blocks with their info strings intact — the mirrors reproduce your source, not the rendered HTML.
---
# Admonitions, tabs and diagrams
_Trail / Writing_
> Three block-level extensions on top of markdown — GitHub-style callouts, tabbed alternatives for per-platform instructions, and mermaid diagrams rendered from text.
Three constructs on top of ordinary markdown handle the things prose alone does badly: setting something apart, showing the same instruction several ways, and drawing.
## Admonitions
Admonitions use GitHub's alert syntax — a blockquote whose first line is a marker:
```markdown
> [!IMPORTANT]
> **Pekit supersedes the old `peipkg-build` recipe system.** A pekit recipe
> is the current and only supported way to build a package.
```
Five kinds exist, and no others:
| Marker | Renders as | For |
|---|---|---|
| `> [!NOTE]` | Note | An aside worth knowing, not worth interrupting for. |
| `> [!TIP]` | Tip | A shortcut or a better way. |
| `> [!IMPORTANT]` | Important | Something a reader who skims will regret missing. |
| `> [!WARNING]` | Warning | Something that will go wrong. |
| `> [!CAUTION]` | Caution | Something that will go irreversibly wrong. |
The body is full markdown — lists, code blocks, links, all of it.
A blockquote whose first line looks like a marker but is not one of the five is a **build error**, not silently-rendered text:
```text
unknown admonition type '[!WARN]' (expected NOTE, TIP, IMPORTANT, WARNING or CAUTION)
```
That is deliberate. A typo'd marker renders as a quotation with `[!WARN]` sitting at the top of it, which nobody proofreading their own page ever notices.
An ordinary blockquote — no marker — is still an ordinary blockquote.
## Tab groups
Tab groups show the same instruction several ways, so a page does not have to repeat itself per platform, per shell, or per package manager.
````markdown
:::tabs
:::tab Linux
Install with your package manager:
```sh
sudo apt install trail
```
:::tab macOS
```sh
brew install trail
```
:::
````
The grammar is three markers, each alone on its own line:
| Marker | |
|---|---|
| `:::tabs` | Opens a group. |
| `:::tab
```
The browser can then reserve the right space before the file arrives, so text does not jump around as images load. SVGs get no dimensions — they scale — and neither does any file whose header cannot be read.
## Captions and figures
An image with a **title** — the quoted string after the destination — that sits alone in its own paragraph becomes a `