Migrate documentation from MkDocs to Zensical

[corentin-core]

Context

MkDocs is experiencing a leadership crisis: maintainer conflicts, stalled development (no release since August 2024), and a proposed v2 that removes plugin support entirely — which would break the Material theme we rely on.

Zensical, built by the Material for MkDocs team, is the natural successor. It reads existing mkdocs.yml files natively and builds 5x faster.

Reference: https://fpgmaas.com/blog/collapse-of-mkdocs/

Proposed solution

• Replace mkdocs with zensical in dependencies
• Verify the documentation builds correctly with Zensical (themes, Mermaid diagrams, pymdownx extensions)
• Adapt mkdocs.yml if any breaking changes exist
• Update CI/CD pipeline if applicable

Acceptance criteria

• Zensical installed and building the docs successfully
• All pages render correctly (navigation, code blocks, Mermaid diagrams, admonitions)
• mkdocs.yml updated if needed
• Dependencies updated in setup.cfg

[corentin-core]

Still relevant, not urgent — keeping as a watch item.

Upstream state (mid-2026): Material for MkDocs is in maintenance mode (critical + security fixes only, committed through ~November 2026); new work has moved to Zensical, the official successor from the same team. Zensical reads mkdocs.yml natively and is usable today provided a project only needs already-implemented features.

That proviso is the blocker here: our docs rely on Mermaid diagrams and pymdownx extensions, and the acceptance criteria require those to render correctly. Feature parity in Zensical is still partial, so the migration can't be validated until Mermaid + pymdownx are confirmed supported.

Plan: hold as low-priority watch. Revisit once Zensical covers Mermaid + our pymdownx extensions, or sooner if a critical MkDocs issue forces our hand before the ~Nov 2026 support horizon.

Refs: https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/ · https://zensical.org/docs/community/faqs/