Skip to content

ADR-0002 — Docs toolchain: MkDocs Material, pinned

  • Status: Accepted
  • Date: 2026-07-26

Context

The documentation site is the primary artifact of this project — the code exists to support the argument, not the other way round. The toolchain choice therefore matters more than it would on a typical codebase.

MkDocs Material was chosen for Markdown-native authoring, first-class Mermaid support (this project is about graphs), and mkdocstrings API generation from the same repo.

Shortly after adoption, an upstream governance problem surfaced. Material's own build output warns that MkDocs 2.0 will:

  • remove the plugin system entirely, which Material depends on
  • replace YAML configuration with TOML
  • close the contribution model
  • ship currently unlicensed

Material's maintainers are not following MkDocs 2.0. They have built Zensical, a separate backward-compatible generator, and Material's future development targets it.

Decision

Stay on MkDocs Material and pin the documentation toolchain to exact versions.

mkdocs==1.6.1
mkdocs-material==9.7.7
mkdocstrings[python]==1.0.6
pymdown-extensions==11.0.1

Development tooling (ruff, mypy, pytest, hypothesis) stays on floating minimums. Freeze the fragile part; let the healthy part float.

Revisit when the site goes public at the end of Phase 1 — the point at which visual identity begins to matter — not before.

Revisit trigger fired 2026-07-26

The site is now public at swarmplane.dev, so this deferral has expired rather than silently lapsed. No action taken yet: the pinned toolchain builds clean and Phase 2 is implementation work, not design. The open choice is whether to follow Material to Zensical or migrate to Astro Starlight for a distinctive visual identity. Recorded here so the decision is made deliberately rather than by drift.

Rationale

The gate for this project is Phase 1, and Phase 1 is writing. Rebuilding the toolchain now spends the scarcest resource on infrastructure rather than on the essays that are the deliverable. Material builds clean today. Content is Markdown, so the exit cost stays low whichever way the ecosystem settles.

Consequences

Positive — no rework now; writing starts immediately; an incidental uv sync cannot silently break the site.

Negative — pinned dependencies will not receive security or bug fixes without a deliberate bump; a migration to Zensical or another generator is deferred, not avoided.

Alternatives rejected

Astro Starlight now. Stable toolchain, no governance risk, considerably more design freedom, and the Node toolchain is already required by ui/ for the graph visualizer and A2UI renderer — so the "extra toolchain" objection does not hold. Rejected only on timing: its advantage is visual identity, which pays off at launch, not during drafting. This is the leading candidate if a migration becomes necessary.

Follow MkDocs 2.0. Not viable — it would mean abandoning Material, Mermaid support, and mkdocstrings simultaneously, in favour of an unlicensed project.

Known issue

Material renders Mermaid diagrams into a closed shadow root (attachShadow({mode: "closed"})). Diagram content is therefore invisible to querySelector from page JavaScript. Any test asserting on rendered diagrams must use screenshots or layout metrics, never DOM queries. This will apply to the graph visualizer if it is embedded in these docs.

Unresolved: Material's themeCSS sets .node rect { fill: … }, which may override classDef colours in diagram source. Verify visually before relying on custom node colours.