Skip to content

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

We are launching Zensical now that our foundational work is completed. While we work to achieve feature parity with Material for MkDocs, we invite our professional users to join us in designing features coming up on our roadmap. We are launching Zensical Spark as a collaborative space where features needed for complex projects can be discussed, prototyped, and designed.

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 1a: 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 1b: 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, users will be able to build MkDocs projects transparently with Zensical.

  • Phase 2: Finish the module system and use it to create modules guided by discussions in Zensical Spark. By providing Zensical's functionality as a set of built-in modules, we deliver a strong developer experience and lay the foundation for a thriving third-party ecosystem.

  • Phase 3: 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 1b and phase 2. Over time, we will introduce more and more features from our roadmap.

Additionally, we will provide tools for transitioning projects one step at a time as well as support through Zensical Spark. For example, when we introduce support for components, we will provide a tool that converts the existing syntax provided by Markdown extensions to components.