Migration path from Onion MkDocs to Onion Zensical

Description

Material for MkDocs is being deprecated in favor of Zensical.

Timeframe: current codebase supported until 2026-11.

We're aware that transitioning takes time, which is why we commit to support it at least for the next 12 months, fixing critical bugs and security vulnerabilities as needed, but the path forward is with Zensical.

This ticket is about offering a migration path from Onion MkDocs to Onion Zensical.

Tasks

• Preparation:
  • Bootstrap the Onion Zensical project, by creating the onion-zensical repository as a fork from onion-mkdocs, with CI and test data to help the migration process.
  • Setup a monthly pipeline schedule.
  • Create an admonition in the Onion MkDocs site pointing to this migration plan.
  • Point to this migration plan in the README. No need for that, as the warning in the site is enough.
  • Create a migration plan.
• Migration:
  • Phase 0: assessment:
    • List all projects using Onion MkDocs.
    • Build a feature matrix based on Zensical compatibility document, the roadmap, the planned plugins and the features needed by each project, including:
      • Support for custom heading references { #like-this }.
  • Phase 1: projects are migrated to keep things working after MkDocs Material is phased out:
    • Migrate each site once it's required features are available.
    • Track issues found, like:
      • Zensical seems not to support symlinks as assets.
    • Move sites listed in Onion MkDocs "live examples" documentation section into the corresponding Onion Zensical section.
  • Phase 2: re-evaluate whether projects should be migrated to alternatives.
    • Evaluate migration from Onion Zensical to other tools and considering the work being done in the TPA-RFC-38 scope.

Time estimation

• Complexity: medium (3 days)
• Uncertainty: high (x2)
• Reference (adapted)