MkDocs 2.0 and its impact

With many of you considering to migrate from MkDocs 1.x to Zensical, the recent pre-release of MkDocs 2.0 has prompted a lot of questions. We've done the analysis, and the short answer is: this is exactly why we started Zensical. Our effort to provide the ecosystem with a reliable, open foundation and a new home has never mattered more than it does right now. Read on to learn more.

MkDocs 2.0

MkDocs 2.0 was announced, and it seeks to be a fundamental shift away from the ecosystem that evolved around MkDocs 1.x, trusted by tens of thousands of projects. From our perspective, the following issues are cause for concern:

• All plugins will stop working – the plugin system has been removed
• All theme overrides will break – the theming system has been rewritten
• No migration path exists – existing projects cannot be upgraded
• Closed contribution model – community members can't report bugs
• Currently unlicensed – it's unsuitable for production use

In summary: MkDocs 2.0 does not support building MkDocs 1.x projects, which is what many of you are depending on right now as users of Material for MkDocs. We analyzed the situation in-depth in a blog post, which we are continuously updating.

Don't panic!

MkDocs 1.x is still available, although unlikely to receive any updates. As a temporary solution, we recommend pinning your projects to MkDocs 1.6.1, the latest version. With no updates in the past 18 months, we strongly advise to start treating MkDocs as a supply-chain risk that needs to be actively managed.

The right time to start planning your migration is now, especially if your projects are large and complex. We understand that intuitively, it might seem that waiting for Zensical to be a complete drop-in replacement is a viable option, but we recommend to analyze your specific requirements and discuss them with us.

Don't just take our word for it – have a look at MkDocs 2.0, evaluate the implications for your own projects, and consider all available options. If you have any questions, just reply to this email.

Help us make Zensical sustainable

If you've been a happy user of Material for MkDocs, consider supporting our work by joining Zensical Spark. As a small team, we depend on your financial support to make Zensical sustainable as an Open Source project, enabling you to create and maintain your documentation projects using open standards instead of proprietary tools.

You'll get hands-on migration support by the team that maintained Material for MkDocs for the past 10 years, among many other benefits.

Highlights

Modes of navigation

We have continued work on modular navigation, outlining how we make navigation scalable and more usable for large sites, which is achievable through the concept of pruning. The following diagram shows seven possible modes of navigation pruning that could allow for more flexibility, which we're currently experimenting with:

Using nav.toml files in different sections, authors can apply these pruning strategies to produce the right balance between pruning effectiveness and user experience. We updated ZAP 005 to include several new scenarios that illustrate the use of pruning strategies, and show how they can be combined to serve specific project needs. Authors would be able to define other aspects of navigation in nav.toml files – change title precedence, sort order, or define navigation for multi-language sites.

We started building the first prototypes for modular navigation to understand design requirements and implications, and to explore the problem space. We will shortly make them available for experimentation and feedback in Zensical Spark.

In other news

• We released three new versions in February, the latest being 0.0.24.
• We added support for the autorefs MkDocs plugin in 0.0.22.
• We focused our development efforts on finishing the module system.
• We just crossed 250,000 monthly downloads – adoption keeps growing.
• The static-i18n plugin entered maintenance mode in light of MkDocs 2.0.
• Linux Foundation study finds: supporting OSS can yield up to 5x ROI.

What's next

We're closing in on a release of the module system in March, and shortly after, will make the module API available in Zensical Spark. The module system lets us move quickly toward feature parity with Material for MkDocs, by bringing plugin functionality from MkDocs plugins (e.g. awesome-nav) into native Zensical modules. The module API will allow everybody to build custom modules for Zensical.

Your voice matters

Our community is growing daily, and we're overwhelmed by the positive feedback we receive about Zensical. Here's one of our favorite messages from last month:

Wonderful product in a turbulent sea of existing static site generators. Super simple to setup and use. You can stand up an entire document site in a matter of minutes and customise it extensively without having to write a single line of code. [...] Highly recommended.

— Ethan Cane

Do you have questions, suggestions, or anything else on your mind? Is there anything you would like to see in future issues of Zensical Monthly? Hit reply and let us know!

Thank you for building with Zensical!