The documentation is one site, built from docs/ and the documents its nav names elsewhere, and each document stays where whatever reads it looks for it¶
Decision 739 · accepted · 2026-09-30 · issue #51
Now mkdocs.yml at the root builds a site with MkDocs Material, which #51 names, and
.github/workflows/pages.yml builds it on every pull request and publishes it from main
to GitHub Pages, at it-minds.github.io/troupe until the product site (#189) gives it a
domain. The build is strict: a link to a page that is not there, a #fragment naming no
heading of it, a nav entry to a missing file, or a page left out of the nav fails it.
Heading anchors are spelt as GitHub spells them, so one #fragment works in both places.
The nav is by reader — using Troupe, running a deployment, contributing, writing a client
— each in the order to read it, and docs/README.md says the same in prose for whoever
reads the repository on GitHub. MkDocs and its theme are pinned in docs/requirements.txt
and Dependabot moves them monthly, but not MkDocs to 2: that drops the plugin and theme
systems the site is built on, and Material requires 1, so leaving MkDocs 1 is a choice for
the product site (#189) to make, not a bump.
Where documents live. MkDocs builds one directory, and several documents a reader
needs are read where they are by something else: the TUI's tests read
PROTOCOL.md's error table, the core's config test reads the YAML in the TUI's and
the daemon's READMEs, GitHub finds CONTRIBUTING.md, SECURITY.md and
CODE_OF_CONDUCT.md at the root, and code cites ARCHITECTURE.md, PROTOCOL.md and
decisions by number. So none of them moved. A nav entry that names no file in docs/
names one by its path from the root, and docs/overrides/hooks.py puts that file on
the site at the same path. Links stay written for GitHub, relative to their file, and
scripts/doc-links.exs keeps checking them; the hook rewrites each one for the site,
to the page where the site has it and otherwise to the file on GitHub at main, and
one that names nothing in the repository fails the build. A copy in docs/ would be
a second version to drift, a symlink fails on a Windows checkout, and a plugin for it
would be a dependency doing what a page of Python does. The hook also reads VERSION
into the banner every page carries, so the site says which release it describes.
The root. It holds what somebody arriving at the repository needs, and what a tool reads
there. The three DECISIONS.md files stay where they are: append-only records that
changes add to while others are in flight, cited by number, and a reader gains nothing
from their moving. The two plans under docs/plans/ and docs/program/ stay too, because
56, open, names them by path. The clients' READMEs stay as each directory's front page,¶
and are the user's and the contributor's pages for their client on the site.
Diagrams are Mermaid in the source. No diagram is a checked-in image;
repo-structure.md's annotated tree is a listing and stays text.
Governs: .github/dependabot.yml