Skip to content

ADR-0007 — Documentation site is MkDocs + Material for MkDocs

Status

accepted

Context

By session 10 the project had accumulated ~30 markdown files under a flat docs/ directory: plans, research, architecture notes, patches. The directory was navigable but only by grep — there was no topic grouping, no rendering, no status metadata, no cross-link validation, no way to spot broken links automatically, and no shareable URL for readers who are not in the repo.

The user asked for "полная реорганизация" with an actually-rendered site, structured topic hierarchy, ADR framework, status badges, and a path to GitHub Pages deploy. The first question that had to be answered was which static site generator the project should commit to.

The candidates evaluated in session 10:

  • MkDocs + Material for MkDocs — Python-based, Markdown-first, extremely capable Material theme, deeply tested by the Python tooling community. Plugin ecosystem is strong. Integrates with GitHub Pages trivially.
  • Sphinx — more powerful but RST-first; adapting to pure Markdown adds friction, and Sphinx's theming surface is larger than we need.
  • Docusaurus / Starlight / Hugo+Doks — healthy JS-based generators, but adding a Node.js toolchain to a Go project with a single Python subprocess would be a third runtime.
  • Pure README.md rendering on GitHub — lowest effort but loses everything the user asked for (topic hierarchy, status badges, cross-link validation).

MkDocs + Material won on four axes simultaneously: Markdown-first, Python-only addition (we already have Python via tunneld/venv), GitHub Pages ready out of the box, and the Material theme's custom admonitions are the exact mechanism the project's verified / hypothesis / gap / superseded status vocabulary needs.

Decision

The iosmux documentation site uses MkDocs as the generator and Material for MkDocs as the theme. Specifically:

  • mkdocs.yml at the repo root, docs_dir: docs, strict: true.
  • Topic hierarchy under docs/: architecture/, plans/, research/, adr/, patches/, runbooks/.
  • Custom admonitions (verified, hypothesis, gap, superseded) wired through docs/stylesheets/extra.css.
  • Content authoring in pure Markdown + YAML frontmatter for status metadata.
  • Python dependencies pinned in docs/requirements.txt (direct deps) and docs/requirements-lock.txt (full transitive lock).
  • Build and serve via scripts/docs-{venv-setup,build,serve}.sh out of a project-local venv at /home/op/venvs/iosmux-docs.
  • GitHub Pages deploy via Actions (Phase 6 of the reorganization).

This ADR captures the category choice — MkDocs + Material as the engine family. A separate ADR (ADR-0008) captures the ratification of the specific pinned state and the October 2026 reevaluation point that the 2026-Q1 ecosystem split made necessary.

Consequences

Wanted:

  • First-class rendering of the existing Markdown files with Mermaid diagrams, hex dumps, and code blocks preserved.
  • mkdocs build --strict catches broken cross-references at build time, eliminating a class of silent rot.
  • Status metadata is machine-readable via frontmatter and human-visible via the custom admonition badges.
  • GitHub Pages deploy is a few lines of YAML.

Accepted as cost:

  • A Python venv dedicated to docs (separate from the tunneld venv). We already have Python in the project so the marginal cost is small, but it is a second venv to manage.
  • Some authoring conventions: YAML frontmatter on key files, .pages files for navigation ordering, relative-path discipline so strict link validation keeps passing.

Evidence

  • plans/docs-reorganization.md — self-contained execution plan, Appendix B for the mkdocs.yml template.
  • mkdocs.yml at the repo root — the actual config that implements this ADR.
  • docs/stylesheets/extra.css — custom admonition definitions referenced by this ADR as the concrete mechanism.
  • scripts/docs-build.sh — the build command that runs with --strict.

References

  • ADR-0008 — specific pinned state, October 2026 reevaluation point, and the post-session-10 ecosystem research that amended this decision's risk profile.