# 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. Related content: - [What is Trail](/trail/getting-started/what-is-trail.md) - [Products](/trail/structuring-a-site/products.md) - [Directory and file names](/trail/reference/directory-names.md) - [trail.toml reference](/trail/reference/trail-toml.md)