id: ADR-0036 title: Publish the documentation as an mdBook on GitHub Pages status: accepted date: 2026-09-13 deciders: [paul-heyse] level: decision principles: [DM-55, DM-49] blueprint: [§0.1, §0.3] review: not-required: a documentation-tooling decision; neither review raised a finding against it evidence: Proposed supersedes: [] superseded-by: null revisit: The Python package grows a public surface that needs generated API documentation (register row R-14), or the book outgrows a single SUMMARY.md verification: docs / build (adr.py index --check, mdbook build docs, lychee --offline); docs / deploy on main

ADR-0036: Publish the documentation as an mdBook on GitHub Pages

Context

The repository’s authority lives in Markdown: the blueprint, the charter, the reviews, the capability maps, the decision records. A reader needs one navigable surface, and the ADR index has to be generated rather than hand-maintained.

Scope

Binds the documentation tool, the site source layout and the build gate. Rust API documentation is cargo doc and is copied in when the artifact exists; Python API documentation is deferred.

Drivers

The source is already Markdown; the book must build without the Rust extension so docs / build stays cheap; internal links must be checked, because a docs site with broken links is worse than a directory listing.

Options

mdBook — selected: Markdown in place, SUMMARY.md as the one navigation authority, a cargo binstall-able pinned binary. MkDocs or Sphinx — rejected: a Python environment on the docs path for a project whose docs are not Python. A directory of files on GitHub — rejected: no link checking and no generated index.

Outcome

mdBook with docs/book.toml (src = ".") and docs/SUMMARY.md, deployed to GitHub Pages from main. The ADR block in SUMMARY.md is generated by scripts/adr.py index between <!-- adr:begin --> and <!-- adr:end -->.

Consequences

Every document that should be readable must be listed in SUMMARY.md; docs/generated/ is committed so the book never needs the extension module built.

Compensating controls

docs / build runs adr.py index --check before mdbook build, so a stale index fails the PR rather than the deploy; lychee --offline checks internal links.

Confirmation

docs / deploy uses actions/deploy-pages from main only; the built book is gitignored.

Pros and cons

mdBook’s single SUMMARY.md is a bottleneck for a large site; it is also the reason nothing can be published unlisted.

More information

Blueprint §0.1, §0.3 (reading guide); docs/book.toml; docs/SUMMARY.md; register row R-14.

Status history

• 2026-09-13 — accepted with the repository-seeding pull request (backfilled from blueprint revision 3).