Skip to content

ADR-0004 — Docs toolchain: migration is now time-bounded

  • Status: Accepted
  • Date: 2026-07-26
  • Amends: ADR-0002

Context

ADR-0002 pinned the documentation toolchain to exact versions and deferred the migration question until the site went public. That trigger fired on 2026-07-26. This record captures what the re-evaluation found. ADR-0002 is Accepted and therefore immutable, so this amends it rather than editing it.

Three things were checked.

The MkDocs 2.0 claims in ADR-0002 still hold. Verified against Material's own announcement (18 February 2026, updated 13 April 2026): MkDocs 2.0 is currently unlicensed, "won't have a plugin system," runs a closed contribution model in which users are asked not to open issues or pull requests, and moves configuration to TOML with "no migration path for existing projects." The governance situation has deteriorated since ADR-0002 was written — the previous active maintainer has forked MkDocs 1.x as ProperDocs, and a March 2026 change of PyPI package ownership briefly removed access for the remaining maintainers, including MkDocs' original author.

Material for MkDocs is no longer open-ended. It entered maintenance mode alongside the Zensical announcement of 5 November 2025, its team committing to fix "critical bugs and security vulnerabilities as needed" for "at least the next 12 months." That is a floor with nothing stated beyond it, which places the end of the stated commitment at roughly November 2026.

Zensical is not yet a viable target. It is MIT-licensed, reads mkdocs.yml natively, and replaces rather than removes the plugin system. But the replacing module API is not open: the project is "currently holding back on releasing a public API" until confident no breaking changes loom, and the third-party opening announced for early 2026 has not landed.

Decision

Stay pinned through Phase 2. Choose a migration target by Q4 2026.

The pin and the exact versions from ADR-0002 stand unchanged. What changes is the pin's character: it is no longer an indefinite deferral but a fixed-length runway, bounded by Material's stated support floor.

Rationale

Phase 2 is implementation — the graph types, the frontier, the warehouse demo. Spending it on a toolchain migration would repeat precisely the mistake ADR-0002 avoided, and would do so at the worst possible moment, since the most likely target is not ready to receive us.

Exit cost is low, and stating it precisely is what makes waiting safe rather than complacent. mkdocs.yml declares two plugins: search, which ships with MkDocs core, and mkdocstrings, the only third-party plugin — and per docs/reference/index.md it generates nothing until src/swarmplane exists. Everything else the site depends on is markdown_extensions (pymdownx.*, admonition, toc), which are Python-Markdown extensions rather than MkDocs plugins and travel with the content. The content itself is Markdown. So the "MkDocs 2.0 removes the plugin system" risk currently bites on exactly one plugin, and that plugin is doing no work yet.

Consequences

Positive — Phase 2 proceeds uninterrupted. Deciding later also means deciding with better information: Zensical's module API status will be known, and Starlight's advantage pays off at a launch that has not happened yet.

Negative — the runway is real, and roughly three months of stated commitment remain at the time of writing. If Q4 2026 passes without a decision, the site sits on a generator with no support commitment at all. This record is the only thing standing between that outcome and drift.

Alternatives rejected

Migrate to Zensical now. The obvious successor: MIT-licensed, built by Material's own team, reads mkdocs.yml natively. Rejected on readiness, not merit — its third-party module API is not public, so mkdocstrings, the one plugin that starts mattering the moment Phase 2 lands, has no guaranteed path. Reconsider first when that API opens.

Migrate to Astro Starlight now. Still the leading candidate on merit, for the reasons ADR-0002 gives, and still rejected on the same timing argument: its advantage is visual identity, which pays at launch rather than during implementation.

Adopt ProperDocs. A maintained MkDocs 1.x fork by the previous active maintainer, which would preserve the existing plugin ecosystem with minimal disruption. Rejected for now on durability rather than technical grounds — a fork's long-term maintenance is unproven. Worth reconsidering if the Zensical API slips further.

Let the pin ride and say nothing. Rejected. That is the drift outcome ADR-0002's revisit note existed to prevent, and it converts a deliberate choice into an accident.

What this supersedes

ADR-0002's closing guidance — revisit "when the site goes public at the end of Phase 1 … not before," and the revisit-trigger note appended beneath it — is superseded by the Q4 2026 deadline recorded here. Nothing else in ADR-0002 changes.