Migrate documentation generator from MkDocs to Zensical #255
Description
Context
The Process-PSModule documentation site is built with Material for MkDocs. The Material for MkDocs team has announced Zensical, a modern static site generator built from the ground up to replace MkDocs. MkDocs itself has had no releases since August 2024 and is accumulating unresolved issues, creating a supply chain risk.
Request
The documentation generator should be migrated from Material for MkDocs to Zensical to ensure long-term maintainability and take advantage of performance improvements.
Why this matters
- MkDocs is unmaintained: No releases since August 2024, accumulating unresolved issues and PRs
- Material for MkDocs is in maintenance mode: Supported for at least 12 months, but the path forward is Zensical
- Performance: Zensical offers 4–5× faster rebuilds during development via its ZRX differential build engine
- Modern search: Disco, a new client-side search engine with improved ranking, filtering, and aggregation
- Sustainability: Fully open source (MIT licensed), actively developed
Compatibility
Zensical reads existing mkdocs.yml configuration, works with existing Markdown content, and supports template overrides, CSS, and JavaScript extensions as-is. Some MkDocs plugins may not yet have equivalents — see the compatibility documentation.
Acceptance criteria
- Documentation builds successfully with Zensical
- All existing content renders correctly
- Search functionality works
- CI/CD pipelines are updated
- No regressions in navigation, theming, or extensions
Technical decisions
Migration timing: Phase the migration — evaluate in Q1 2026, migrate once the module system is available (early 2026), adopt component system and CommonMark in Q3 2026.
Plugin compatibility: Review all currently used MkDocs plugins against the feature parity status before migrating.
Configuration approach: Start with the existing mkdocs.yml and address incompatibilities incrementally.
Implementation plan
Phase 1 — Evaluation
- Review current MkDocs plugins in use and check Zensical compatibility
- Install Zensical locally and test builds with existing configuration
- Identify any breaking changes or missing features
Phase 2 — Migration
- Update documentation build workflows to use Zensical
- Update CI/CD configuration
- Test all documentation features (navigation, search, extensions)
- Address any plugin incompatibilities
Phase 3 — Adoption
- Monitor for module system release (early 2026) and adopt when available
- Evaluate component system and CommonMark migration