Task: Plan Migration from MkDocs to Zensical (MkDocs 2.0 Compatibility)

[ahouseholder]

⚠️ Task: Plan Migration from MkDocs to Zensical (MkDocs 2.0 Compatibility)

Context

The Material for MkDocs team has announced that the upcoming MkDocs 2.0 is a ground-up rewrite that is incompatible with the current mkdocs-material theme and its plugin ecosystem.

Specifically, MkDocs 2.0:

• Removes the plugin system entirely.
• Changes the config format from YAML to TOML.
• Breaks existing themes, as navigation is now passed as pre-rendered HTML rather than structured data.

The Solution: Zensical

To maintain the current look, feel, and functionality of our documentation, we will need to eventually migrate this project to Zensical. Zensical is a modern static site generator built by the same team behind Material for MkDocs, designed specifically to be a backward-compatible "home" for MkDocs 1.x projects.

Impact on this Project

• Config: Our mkdocs.yml is currently supported by Zensical, but we should monitor for any required minor adjustments.
• Plugins: We need to verify if the specific plugins used in this repo are currently supported by Zensical's feature parity roadmap.
• Build Pipeline: Our CI/CD (GitHub Actions/Lab) will need to swap the mkdocs build command for the zensical equivalent once the transition begins.

Proposed Action Plan

1. Monitor: Track the official release of MkDocs 2.0 and Zensical's stable version.
2. Audit: List all plugins used in mkdocs.yml and check Zensical compatibility.
3. Trial Build: Attempt a local build using Zensical to identify any CSS/template override breakage.
4. Migrate: Update requirements and CI scripts.

References

• Official Blog Post: What MkDocs 2.0 means for your projects
• Zensical Documentation

[sei-renae]

Might obsolete #450

[sei-renae]

Depends on #1101