Anatomy of a site

6 min read

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 is the same material as an exhaustive table; Structuring a site covers each kind of container in depth.

The whole shape #

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.

The parts:

• <order> 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.
• <slug> 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.
• <kind> is antho, topic, book or shelf.

Inside books, an order may also be written a<N>-- (a1--glossary.md). Those are appendices: lettered A, B, C instead of numbered, and sorted after every numbered sibling at their level. See Books.

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.

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/<topic>, 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:

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.

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.

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 <order> prefix, ascending. Within a book, appendix entries (a<N>--) 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 — the product level in depth, and when to add another one.
• Anthologies and shelves — grouping a large product.
• Topics and folders — the everyday container.
• Books — numbered, ordered documents with chapters and appendices.

Edit this page