[Feature]: Plan migration off Material for MkDocs before its Nov 2026 EOL

[santosr2]

Problem Statement

Our documentation site is built with Material for MkDocs (docs/site/, pinned in docs/site/requirements.txt), which is now on a countdown to end of life:

• Maintenance mode since 9.7.0 (Nov 2025) — no new features, only critical bug fixes and security updates.
• Scheduled end of life on November 5, 2026. After that date there are no further fixes, including security fixes.
• Every mkdocs build already prints a MkDocs 2.0 incompatibility warning to stderr (visible in our docs.yml builds and locally via mise run docs:build). Material for MkDocs currently pins mkdocs<2, so the upstream MkDocs 2.0 release is a second, independent breaking change looming over the same toolchain.

This surfaced in #255 (the 9.7.7 bump), whose release notes carry the EOL warning verbatim. Left unaddressed, we would be shipping public docs on an unmaintained generator with unpatched security exposure sometime after Nov 2026.

Sources:

• Bump that surfaced it: ci(deps): bump mkdocs-material from 9.7.6 to 9.7.7 in /docs/site #255
• Zensical announcement: https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/

Proposed Solution

Track and plan a migration of the docs site off Material for MkDocs before the Nov 5, 2026 EOL, comfortably ahead of that date so it isn't a fire drill. Rough shape of the work:

1. Evaluate Zensical (https://zensical.org), the maintainers' designated successor, as the primary candidate — assess feature parity for what we actually use (nav, search, code blocks, admonitions, mermaid, the theming/branding in docs/site/).
2. Confirm it can reproduce the current site output and that mkdocs build --strict-equivalent link/anchor checking still exists (our docs.yml and pre-commit rely on a strict build).
3. Port docs/site/mkdocs.yml config, plugins, and requirements.{in,txt}, then wire the new builder into docs.yml (GitHub Pages deploy) and the mise run docs:* tasks.
4. Verify the GitHub Pages deploy and internal links, then update CONTRIBUTING/dev docs that reference the mkdocs workflow.

No user-facing behavior change is intended — this is docs-infrastructure tech debt. This issue is a tracking/planning placeholder; the actual approach should go through the normal spec/plan flow once we pick up the work.

Alternatives Considered

• Stay on Material for MkDocs past EOL — rejected: unmaintained tooling for public docs, no security patches after Nov 2026.
• Migrate to a different generator (e.g. plain MkDocs on a still-maintained theme, Docusaurus, Hugo, mdBook) — worth weighing against Zensical during evaluation, since MkDocs core itself is heading to a breaking 2.0 and the whole MkDocs ecosystem is in flux. Zensical is the low-friction default given it's the maintainers' own successor and content is largely Markdown, but it's young; the evaluation step should not assume it wins.
• Do nothing yet — acceptable short-term (EOL is ~15 months out), which is why this is a tracking issue rather than immediate work, but we should not let it slip past mid-2026.

Feature Area

Documentation

Notes

• Not urgent, but should be scheduled well before Nov 5, 2026 rather than at the deadline.
• Whoever picks this up: start by pinning down our actual Material feature usage in docs/site/mkdocs.yml — that list is the real migration scope.