Compatibility¶

Zensical is designed for seamless compatibility with Material for MkDocs. In many cases, you can install Zensical and build your projects immediately – no changes to configuration or content.

However, Zensical is more than just compatible – it's a complete replacement for both MkDocs and Material for MkDocs. While Material for MkDocs is built on top of MkDocs as a theme and framework, Zensical consolidates both projects into one coherent stack, covering static site generation, theming, and customization.

Consult the configuration section to learn how Zensical understands your existing mkdocs.yml, the features section to verify your specific requirements are already supported, our roadmap to learn what's coming, and what we've planned for third-party plugins from the MkDocs ecosystem.

What stays the same?¶

We've designed Zensical to be as compatible as possible with Material for MkDocs and with the broader MkDocs ecosystem. We maintain compatibility across these key areas:

• Build configuration – Use your existing mkdocs.yml file. No new config format to learn, and no need to create a zensical.toml.

• Content and front-matter – Python Markdown and all extensions work without changes. Your existing content builds as-is.

• Project structure and URLs – Files stay where they are. URLs and anchors remain identical, preserving bookmarks, external links, and SEO.

• Template overrides – Minor adjustments for MiniJinja compatibility (already shipped in recent Material for MkDocs versions). HTML structure remains unchanged.

• Custom CSS and JavaScript – Generated HTML, CSS variables, and JavaScript APIs remain compatible with your existing customizations.

Phased transition strategy¶

While the roadmap lists features we are working towards, here's what we imagine the experience of using Zensical will look like over time. We organize our efforts in three phases:

• Phase 1: Establish maximum compatibility with Material for MkDocs. This involves carrying over essential parts such as Python Markdown, Markdown extensions, and the Jinja templates. While this choice initially limits performance improvements, it ensures an easy transition.

• Phase 2: Release the module system, start creating modules for new features guided by discussions in Zensical Spark, and work towards feature parity with Material for MkDocs, laying the foundation for a thriving third-party ecosystem.¹

• Phase 3: Reach full feature parity by providing the functionality implemented within plugins shipped with Material for MkDocs and popular third-party plugins from the ecosystem. At this stage, most users will be able to build MkDocs projects transparently with Zensical.

• Phase 4: Introduce the component system and CommonMark support. With a Rust-based CommonMark parser replacing Python Markdown, we gain both modularity and performance. The component system also enables easier and more flexible templating.

Those phases will not necessarily be completed sequentially, but will overlap, especially phase 3 and phase 4. Over time, we will introduce more and more features from our roadmap.