Migrate documentation from MkDocs to Zensical

[titusz]

Summary

Migrate our documentation build from MkDocs + Material for MkDocs to Zensical, the successor static site generator built by the Material for MkDocs team.

Background

Material for MkDocs has entered maintenance mode (critical bugs/security only, no new features) since the underlying MkDocs project has been unmaintained since August 2024. The team's efforts have shifted to Zensical. Additionally, MkDocs 2.0 introduces breaking changes and is incompatible with Material for MkDocs.

Zensical is designed as a drop-in replacement — it reads mkdocs.yml directly, supports Python Markdown and all extensions, and existing content builds as-is in many cases.

Benefits

• Actively developed — MkDocs/Material are in maintenance mode
• Faster rebuilds — 4-5x faster incremental builds during serve
• Better search — Disco, a modular client-side search engine
• Future-proof — new Rust-based Markdown toolchain in progress
• High compatibility — existing mkdocs.yml and content work with minimal changes

Migration Steps

• Add zensical as a dev dependency (available via pip/uv)
• Verify current docs build with zensical build using existing mkdocs.yml
• Check compatibility of all plugins we use:
  • search
  • autorefs
  • mkdocstrings (Python handler with Sphinx-style docstrings)
• Check compatibility of markdown extensions (pymdownx suite, admonition, etc.)
• Test theme features (dark/light toggle, navigation tabs, custom CSS)
• Verify custom overrides directory (docs/overrides) works
• Update CI workflow (.github/workflows/ci.yml) to use zensical for doc builds
• Update pyproject.toml dev dependencies (replace mkdocs packages with zensical)
• Update any build scripts (devtools/build_docs.py, poethepoet tasks)
• Test full doc site locally and verify deployment to https://sdk.iscc.codes

References

• Zensical announcement
• Zensical compatibility guide
• Zensical GitHub
• MkDocs 2.0 breaking changes