Plugins¶

To understand which plugins we need to bring over from MkDocs to Zensical, we have conducted a quantitative analysis of the top 1,000 repositories on GitHub using Material for MkDocs, as well as a qualitative evaluation of the MkDocs plugin catalog. In this section, we share our strategy for supporting the most popular MkDocs plugins to make migration seamless.

MkDocs plugin support¶

We commit to support the following plugins, and thus have added all of them to our backlog. We deliberately split those plugins into two tiers, with Tier 1 being the highest priority. Plugins are listed in alphabetical order here to make them easier to find:

Tier 1¶

Tier 2¶

Read on to learn more about how we are ensuring compatibility with these plugins in the short term and how we will evolve the functionality in the longer term to make use of Zensical's full capabilities, ensure sustainability, and re-think designs where appropriate.

How we are building the module ecosystem¶

Phase two of our phased transition strategy begins with the completion of the initial release of our module system, which allows us to rapidly expand the functionality Zensical provides and work towards feature parity with Material for MkDocs, allowing more projects to migrate to Zensical.

We've decided to fast-track compatibility with the MkDocs plugins listed above by mapping their existing configuration in mkdocs.yml – or in the project scope in zensical.toml – to Zensical modules we are now gradually developing.

This approach ensures that most existing MkDocs projects using these plugins can be built with Zensical as they are, with no changes in configuration, content, or customizations needed.

Our goals¶

We're commited to ensure a smooth transition to Zensical for Material for MkDocs users. By mapping the functionality of MkDocs plugins to Zensical modules we are honoring this commitment while aiming to deliver the following advantages:

• Stewardship: Unfortunately, while the MkDocs ecosystem has become central to many organizations practicing Docs-as-Code, it has never experienced the level of coordination and stewardship to match its importance.

• Consolidation: Instead of having to hunt for and assess a set of plugins that together satisfy a project's needs, users can get more batteries included by just installing Zensical. Consolidating functionality ensures coherence, consistent maintenance, and compatibility, ands puts all documentation in one place.

• Leveraging the capabilities of the Zensical runtime: Right now we have a mix of Rust and Python code to ensure compatibility. We're gradually migrating all functionality to Rust to improve performance, robustness, security, and maintainability. Modules in Zensical benefit from parallel execution, caching, and the active avoidance of duplicate work.

• Flexibility: Thanks to the modularity of Zensical, it will still be possible to replace these modules with third-party ones, so we are fostering community innovation while providing strong defaults. Third-party modules can be implemented in Rust. We are working on supporting writing modules in Python as well.

Re-thinking functionality¶

In phase four, when we have achieved feature parity, the focus will shift to implementing functionality that we have researched and prototyped as part of the Zensical Advancement Proposals (ZAP) process. You will, of course, still be able to build Material for MkDocs projects. New functionality will be available through the new zensical.toml configuration format. We will provide conversion tools to automate the process, so there is no need to switch manually.

Why are we re-thinking functionality? The MkDocs ecosystem evolved under significant constraints – a limited plugin API, a slow-moving core project, and early design decisions that pushed innovation into fragmented, non-coordinated plugin efforts. Plugins themselves were typically built to solve specific problems, and while popular ones grew more generic over time, they remain shaped by the specific use cases that originally motivated them.

With Zensical, we take the opportunity to change how key functionality is implemented. For example, we have written a number of ZAPs to define how we imagine navigation authoring experience to work in the future. ZAPs 001, 003, 004, and 005 together outline a range of use cases that show why we need to implement modular navigation as announced on our roadmap.

Some plugins only came into existence to address limitations caused by MkDocs design decisions. The typeset plugin in Material for MkDocs, for example, serves to allow rich content in navigation labels. As we will be re-designing the way that navigation is defined and will support rich content, this plugin is now deprecated.

Likewise, literate-nav and awesome-nav serve to allow navigation to be treated as content. They provide significant extensions to the base functionality of MkDocs but do so within the constraint that there is only one navigation hierarchy. With the re-design of the navigation system, Zensical will support navigation as content but will go much further than this, supporting navigation elements besides the main hierarchy as well as breaking the main hierarchy into partitions.

Degrees of freedom¶

Our aim is to introduce more degrees of freedom instead of producing opinionated solutions that work for a number of specific use cases but might fail for projects when their requirements evolve as they grow and circumstances change.

In our ZAPs, we focus on exploring the problem space instead of working from the perspective of specific features. We sketch out scenarios that explore different dimensions of the problem space so that the functionality we develop captures degrees of freedom that make the solution applicable to the largest possible part of the identified problem space.

Of course, opening up degrees of freedom may simply trade an opinionated solution for one that is too difficult to understand and match to specific needs. We counter this by introducing presets that narrow down the degrees of freedom according to specific aims. Presets can cover specific aspects of a project configuration and can be combined with each other.

Teams can choose presets for their project but are free to override their settings, or eject them and gain access to the full set of degrees of freedom that Zensical provides. Organizations are enabled to produce their own presets to match their requirements.

Third-party modules¶

With the development of the modules replacing the plugins listed above, we are road-testing the module system. To allow for it to mature, we are currently holding back on releasing a public API. Once we are confident enough that no breaking changes are on the horizon, we will release a public API and iterate on it in Zensical Spark. We will invite key ecosystem maintainers to be part of the process to ensure that the API we develop meets the needs of the ecosystem and fosters a vibrant third-party module ecosystem.

We provide the Zensical core runtime and module system, allowing third-party developers to focus on the business logic of what they want to accomplish, leaving tedious details like orchestration of the data flow, parallelization, and caching to the runtime.