Track Zensical Migration

[Kilo59]

This is a long-term tracking issue for migrating the documentation from the current MkDocs-Material stack to Zensical. Zensical is a high-performance, Rust-based documentation platform built by the original creators of Material for MkDocs.

Context
Zensical represents a direct evolution of the MkDocs ecosystem, featuring a Rust runtime (ZRX) for faster builds, a next-gen search engine (Disco), and a modular architecture. It is currently in alpha, and we should transition once it reaches feature parity with our existing stack.

Blockers & Prerequisites

• Backlog literate-nav: Our docs rely on SUMMARY.md navigation via literate-nav. We must wait for Support mkdocs-literate-nav plugin functionality zensical/backlog#13 to be resolved before a full switch is possible.
• Simplify Stack: Completion of Issue Simplify Documentation Stack: Remove mkdocstrings and gen-files #138 (dropping mkdocstrings/gen-files) is required to minimize the number of custom Python-based plugins needing migration.

Migration Action Plan (Estimated: 3–6 months)

1. Shadow Build Verification

• Once literate-nav is supported, install Zensical (pip install zensical).
• Run zensical build locally against the existing mkdocs.yml.
• Compare the output with the current Material site to ensure visual and structural parity.

2. Switch Deployment

• Switch the doc deployment step in CI from mkdocs build to zensical build.
• Initially, mkdocs.yml can remain unchanged as Zensical provides backward compatibility for it.

3. Modernize Config

• Eventually transition to the native zensical.toml format and opt into the Rust-based optimization engine.

Verification

• Run a shadow build and verify that all core pages and navigation are preserved.
• Verify that the local search engine (Disco) is functional.