Skip to content

Compatibility

Zensical strives to be compatible with Material for MkDocs, allowing you to build your existing projects with minimal changes. We want you to benefit from Zensical's differential architecture and its numerous improvements without requiring significant project modifications. In the ideal case, you can simply install Zensical and start building your existing projects immediately.

To see whether the specific features you are using are already supported, check out the features section. Consult our roadmap to learn where we are heading, what advantages Zensical already offers and what's to come. Also, please review the section on third-party plugins.

Phased transition strategy

We are launching Zensical now that the 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: Develop the module system and use it to create modules inspired 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 might 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.

What stays the same?

In order to ensure that most projects can switch to Zensical with ease immediately, we maintain compatibility across these key areas:

  • Build configuration – Zensical builds your projects using your existing mkdocs.yml configuration file, which means you don't need to create a zensical.toml.

  • Content and front-matter – We support Python Markdown and all of its extensions. Both your page content and front-matter will work without changes.

  • Project structure and URLs – Your files can remain in their current locations, and the resulting pages will have identical URLs and anchors. This preserves existing bookmarks, external links, server-based redirects, and other integrations, which we view as absolutely essential.

  • Template overrides – We've made only small adjustments to templates for minijina compatibility. These changes were already incorporated in Material for MkDocs, so you're likely already using them. The modern design did not introduce any changes to the HTML.

  • Additional CSS and JavaScript – The generated HTML structure, CSS variables, and JavaScript remain unchanged, so your existing customizations will continue to work.