Blog¶

What MkDocs 2.0 means for your documentation projects

Three weeks ago, MkDocs 2.0 was announced – a ground-up rewrite of the documentation tool tens of thousands of projects rely on, introducing potentially significant breaking changes.

We've taken the time to thoroughly evaluate and test the pre-release version, and we want to share what we know, what it might mean for your documentation projects, and where Zensical, our new static site generator that is compatible with MkDocs 1.x, fits into the picture.

If you've missed it: MkDocs 1.x is unmaintained, with issues and PRs piling up and no releases in the past 18 months, and seemingly no plans to fix long-standing issues like live-reload problems. More importantly, it's unclear whether security issues will be addressed, and whether the project will receive any updates at all in the future.

Please note that MkDocs 2.0 is still in pre-release, and the information in this article is based on the current state of the project. We will keep it updated as we learn more.

Goodbye, GitHub Discussions

With the launch of Zensical, we're evolving how we work together with the community to ensure long-term sustainability and professional support, fostering meaningful collaboration.

The launch of Zensical two weeks ago marked a significant milestone, as it establishes a new foundation for our mission to build scalable Open Source systems for technical writing. Additionally, we're adopting a structured, transparent, and community-driven approach to guide the evolution of our projects – prioritizing what to build, and shaping Zensical's future together.

Our new approach distills a decade of experience maintaining Material for MkDocs, allowing us to professionalize and scale our efforts from a small team to a fully organized operation, while keeping the software free and open to everyone.

As Material for MkDocs has entered maintenance mode, our discussion board is now read-only.

In this article, we reflect on the challenges we've navigated, the lessons we've learned, as these experiences have shaped our approach to community management and support that we're building with Zensical.

You can subscribe to our newsletter to stay in the loop.

Material for MkDocs Insiders – Now free for everyone

9.7.0, the final version of Material for MkDocs, includes all features that were previously exclusive to sponsors, making Material for MkDocs Insiders available to everyone!

As we're shifting our efforts to Zensical, Material for MkDocs is entering maintenance mode. This means that while we'll continue to fix critical bugs and security issues for 12 month at least, no new features will be added to Material for MkDocs.

We're also discontinuing our sponsorware model, saying goodbye to GitHub Sponsors. If you were a sponsor of our work, you already received an email mentioning that your sponsorship was cancelled. As one of the numerous individuals and organizations sponsoring Material for MkDocs over the past years – thank you! Your continued support has been invaluable.

Now, we want everyone to benefit from all features we have developed for Material for MkDocs, which is why we're making all Insiders features available to everyone!

This is the logical next step in our journey as we focus on Zensical – our next-generation static site generator built from the ground up to overcome MkDocs' technical limitations. Zensical is fully Open Source, licensed under MIT, maintains compatibility with Material for MkDocs, and can build your existing projects with minimal changes.

In the coming months, we'll close the feature parity gap, bringing the expressiveness of Material for MkDocs to Zensical.

You can subscribe to our newsletter to stay in the loop.

Zensical – A modern static site generator built by the Material for MkDocs team

We are thrilled to announce Zensical, our next-gen static site generator designed to simplify the process of building documentation sites. Distilled from a decade of experience, Zensical is our effort to overcome the technical limitations of MkDocs, reaching far beyond its capabilities.

Zensical is the result of thousands of hours of work – built from the ground up for a modern and comfortable authoring experience, while making it easy for developers to extend and customize Zensical through its upcoming module system. Our goal is to support docs-as-code workflows with tens of thousands of pages, without compromising performance or usability.

To make the transition seamless, compatibility comes first. We're putting significant effort into ensuring a smooth migration from Material for MkDocs for all users. Zensical can natively read mkdocs.yml, allowing you to build your existing project with minimal changes. As of now, a subset of plugins is supported, and we're working on feature parity in the coming months.

Zensical is fully Open Source, licensed under MIT, and can be used for any purpose, including for commercial use. We're also saying goodbye to our sponsorware model, replacing it with our new offering for professional users: Zensical Spark. This allows us to stay independent, maximizing user value, as we shape the future of Zensical together with you.

You can subscribe to our newsletter to stay in the loop.

Transforming Material for MkDocs

We are working on an amazing set of features which has required some behind-the-scenes work we are now ready to share in a series of posts. Here, we give an overview of our goals, features in the making, things that kept us up at night, and our commitment to Open Source.

We know it's been quite a while since our last update, which is why we're eager to share what's happening in and around Material for MkDocs with you. For the largest part of 2024, we've been focused on transforming the core of Material for MkDocs preparing the ground for new, interconnected features that are amongst the most frequently requested.

This article is part of a series where we'll explore how we aim to support our users through improved information retrieval, provide better support for multi-lingual sites and versioning, as well as improve the overall authoring experience. We outline our vision for the projects' evolution and describe what we have been working on. In this and the coming blog posts, we will share our progress with you, and we're excited to hear your thoughts.

Adding a badge to your project

You enjoy working with Material for MkDocs? Share the love! You can now add a badge to your project's README, showing that your project is built with Material for MkDocs.

Material for MkDocs' logo was just added to Simple Icons, which is used by Shields.io to include logos in badges. We generated a badge for you, which you can add to your project's README:

Sunsetting Gitter: Towards Efficient Community Engagement

As we're starting to build a team around Material for MkDocs, we've decided to sunset and archive our Gitter channel on October 13, 2023 in favor of GitHub Discussions.

As part of our efforts to improve the processes for maintaining Material for MkDocs and for supporting the community, we have reviewed the use of different communication channels. At the moment, both Gitter and GitHub Discussions allow to ask the community for support and to discuss ideas and issues. In the past weeks, we have begun to question whether this duplication is in the best interest of our project. This post explains the rationale behind our decision.

Using git sparse-checkout for faster documentation builds

Leveraging git sparse-checkout in GitHub Actions enabled us to speed up documentation builds in our repository, cutting checkout times from 20 to 30 seconds to just 2 seconds.

Developing an efficient approach to build documentation in CI workflows is essential, especially when working in large repositories with thousands of commits, like ours. Of course, we want to build documentation quickly and efficiently, ensuring fast and productive workflows. When using both the wonderful git-committers and git-revision-date-localized plugins to display document contributors and dates at the bottom of each page, we are required to set fetch-depth: 0, which resulted in checkout times of 20 to 30 seconds on our repository. By leveraging git sparse-checkout within GitHub Actions, check out time was brought down to 2 seconds.

Blog support just landed

Hey there! You're looking at our new blog, built with the brand new built-in blog plugin. With this plugin, you can easily build a blog alongside your documentation or standalone.

Proper support for blogging, as requested by many users over the past few years, was something that was desperately missing from Material for MkDocs' feature set. While everybody agreed that blogging support was a blind spot, it was not obvious whether MkDocs could be extended in a way to allow for blogging as we know it from Jekyll and friends. The built-in blog plugin proves that it is, after all, possible to build a blogging engine on top of MkDocs, in order to create a technical blog alongside your documentation, or as the main thing.

Chinese search support – 中文搜索​支持

Insiders adds experimental Chinese language support for the built-in search plugin – a feature that has been requested for a long time given the large number of Chinese users.

After the United States and Germany, the third-largest country of origin of Material for MkDocs users is China. For a long time, the built-in search plugin didn't allow for proper segmentation of Chinese characters, mainly due to missing support in lunr-languages which is used for search tokenization and stemming. The latest Insiders release adds long-awaited Chinese language support for the built-in search plugin, something that has been requested by many users.