René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Migrate to Zensical as primary documentation generator","articleBody":"### Objective\n\nMigrate from Material for MkDocs to [Zensical](https://zensical.org/) as the primary documentation generator for the Process-PSModule solution.\n\n### Background\n\nThe Material for MkDocs team has announced [Zensical](https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/), a modern static site generator built from the ground up to address the limitations of MkDocs. Key motivations for this migration:\n\n**Why Zensical?**\n- **MkDocs is unmaintained**: No releases since August 2024, accumulating unresolved issues and PRs, creating a supply chain risk\n- **Material for MkDocs is in maintenance mode**: Will be supported for at least 12 months but path forward is with Zensical\n- **Performance improvements**: 4-5x faster rebuilds during development\n- **Modern architecture**: Built on [ZRX](https://github.com/zensical/zrx/), a differential build engine enabling better performance and extensibility\n\n### Key Benefits\n\n1. **Performance**\n   - 5x faster rebuilds for incremental changes\n   - Differential build engine processes only changed files\n   - Future: New Rust-based CommonMark parser for even faster Markdown processing\n\n2. **Modern Search**\n   - Disco: New blazing-fast client-side search engine\n   - Improved ranking algorithm\n   - Built-in filtering and aggregation capabilities\n\n3. **Compatibility**\n   - Reads existing `mkdocs.yml` configuration files\n   - Works with existing Markdown content\n   - Template overrides, CSS, and JavaScript extensions work as-is\n   - Minimal changes needed to migrate\n\n4. **Future-Ready**\n   - Module system (early 2026): Deterministic, reusable, topological ordering\n   - Component system: More flexible templating and branding\n   - CommonMark support with automated migration tools\n\n5. **Sustainability**\n   - Fully Open Source (MIT licensed)\n   - Professional support available through Zensical Spark\n   - Active development and long-term maintenance commitment\n\n### Migration Considerations\n\n**What Works Today:**\n- Existing Markdown files\n- Template overrides\n- CSS and JavaScript extensions\n- `mkdocs.yml` configuration (with some plugin limitations)\n\n**Known Limitations:**\n- Plugin ecosystem is being rebuilt with the new module system\n- Some MkDocs plugins may not have Zensical equivalents yet\n- Check [compatibility documentation](https://zensical.org/compatibility/) for current status\n\n**Migration Path:**\n1. Review [feature parity status](https://zensical.org/compatibility/features/)\n2. Install Zensical and test with existing configuration\n3. Address any plugin incompatibilities\n4. Update CI/CD pipelines\n5. Monitor performance improvements\n6. Plan for future module system adoption (early 2026)\n\n### Timeline\n\n- **Phase 1** (Q1 2026): Evaluation and testing\n- **Phase 2** (Q2 2026): Migration once module system is available\n- **Phase 3** (Q3 2026): Adoption of component system and CommonMark\n\n### Resources\n\n- [Zensical Documentation](https://zensical.org/)\n- [Installation Guide](https://zensical.org/docs/get-started/)\n- [Compatibility Guide](https://zensical.org/compatibility/)\n- [Roadmap](https://zensical.org/about/roadmap/)\n- [Blog Post Announcement](https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/)\n\n### Action Items\n\n- [ ] Review current MkDocs plugins and check Zensical compatibility\n- [ ] Install Zensical and test local builds\n- [ ] Identify any breaking changes or missing features\n- [ ] Update documentation build workflows\n- [ ] Update CI/CD configuration\n- [ ] Test all documentation features (navigation, search, extensions)\n- [ ] Monitor for module system release (early 2026)\n- [ ] Plan migration to new module system when available","author":{"url":"https://github.com/MariusStorhaug","@type":"Person","name":"MariusStorhaug"},"datePublished":"2026-01-13T16:11:09.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/255/Process-PSModule/issues/255"}