Material for MkDocs Updates & Release Notes

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.

Available features

Our sponsors have enjoyed exclusive access to the following premium features for quite some time. With the release of 9.7.0, all these features are now available to everyone:

• Blog plugin: pinned posts
• Instant previews
• Footnote tooltips
• Tags plugin: advanced settings
• Tags plugin: nested tags
• Tags plugin: shadow tags
• Stay on page when switching languages
• Blog plugin: author profiles
• Blog plugin: advanced settings
• Projects plugin
• Instant prefetching
• Social plugin: custom layouts
• Social plugin: background images
• Code range selection
• Code annotations: custom selectors
• Privacy plugin: advanced settings
• Optimize plugin
• Navigation path (Breadcrumbs)
• Typeset plugin
• Privacy plugin: external links

mkdocstrings Insiders is now free as well

With Timothée joining the Zensical team, he announced that all features previously reserved to his sponsors as part of mkdocstrings Insiders are now free for everyone as well!

How to upgrade

You can upgrade with the following command:

pip install --upgrade --force-reinstall mkdocs-material

Switching from Insiders

If you've been a user of Insiders, we recommend to switch to the community edition as soon as possible, as it includes all Insiders features. This will make it much easier to handle third-party contributions, since no personal access tokens are necessary.

From now on, bug fixes that we make to Material for MkDocs will only be released to the community edition. Security vulnerabilities will be fixed in both editions.

Thus, please adjust your requirements.txt and GitHub Actions workflows:

- pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
+ pip install mkdocs-material

The Insiders repository itself will remain available for the next 6 months. When you build your project with Insiders, it will now show an informational message pointing to this blog post.

• On February 1, 2026, this message will be turned into a warning.
• On May 1, 2026, the Insiders repository will be deleted.

Sunsetting preparation

Entering maintenance mode, we're preparing Material for MkDocs for sunsetting.

Material for MkDocs grew organically like a plant in a pot that eventually became too small. With Zensical, we're building on solid foundations designed to grow with us – and with you.

Material for MkDocs is in maintenance mode

We want to be transparent about the risks of staying on Material for MkDocs or on forks of both Material for MkDocs and MkDocs. With MkDocs 1.x unmaintained and facing fundamental supply chain concerns, its future is uncertain and we cannot guarantee Material for MkDocs will continue working reliably. MkDocs 2.0 will introduce breaking changes – something we analyzed thoroughly in our MkDocs 2.0 article.

We're aware that transitioning takes time, which is why we commit to supporting Material for MkDocs for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed. If you have questions about your specific situation or need help planning a migration, don't hesitate to reach out at [email protected].

Deprecations

While we release all features to the general public, at the same time, we're deprecating the Projects plugin and the Typeset plugin due to maintainability issues. This means that these plugins will not receive any further updates, including no more bug fixes.

The reason for this decision is that both plugins rely on too many workarounds to make them work with MkDocs, and subsequently have been key motivators to create Zensical. If you rely on these plugins, and they work for your use case, you can of course continue to use them.

With Zensical, we'll be shipping proper sub-project support, including internationalization and versioning, designing these features together with our professional users in Zensical Spark.

Version ranges

Material for MkDocs has used semver version ranges for dependencies to ensure compatibility. With the advent of 9.7.0, we're switching from semver to minimal version ranges. This provides more flexibility in dependency resolution, specifically to allow users to use newer versions of dependencies that include important bug fixes or security patches.

Security

We will not transfer ownership of the Material for MkDocs repository to another individual or organization. The repository and PyPI package will remain under the ownership of @squidfunk, which preserves the trusted supply chain our users depend on.

Thus, if you wish to take on maintenance of Material for MkDocs, please create a fork.

Looking ahead

Achieving sustainability

Where Material for MkDocs relied on sponsorware, Zensical takes a new approach, to ensure it evolves to meet the needs of organizations building complex, enterprise-scale documentation.

Zensical Spark is a collaborative space where professional users have a direct voice in shaping Zensical's future. Through a structured design process and together with our Zensical Spark members, we identify opportunities, validate proposals, and define priorities – turning their real-world documentation challenges into features that benefit the entire community.

Reach out at [email protected] to schedule a call to learn more about Zensical Spark, discuss your organization's needs, and how it helps us to make Zensical sustainable.

Our commitment to you

If you're currently using Material for MkDocs, there's no need to rush. We're committed to keeping it secure and functional for the next 12 months while we focus our efforts on Zensical.

The 9.7.0 release marks a significant shift – every Insiders feature is now available to everyone, with no sponsorship required. As we build Zensical, each of these features will be rearchitected and improved. Zensical is entirely free and Open Source, ensuring the entire community benefits from our work without barriers.

When you're ready to explore what's next, Zensical is compatible with Material for MkDocs and designed to be a natural evolution of the ideas and principles you already know.

If you loved Material for MkDocs and are excited about Zensical, we'll be providing new methods to support our work in the coming months, with the possibility of getting exclusive goodies.

Subscribe to our newsletter to stay in the loop.

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.

This is the second article in a series:

1. Transforming Material for MkDocs
2. Zensical – A modern static site generator built by the creators of Material for MkDocs
3. Material for MkDocs Insiders – Now free for everyone
4. Goodbye, GitHub Discussions
5. What MkDocs 2.0 means for your documentation projects

Why Zensical?

Since its initial release in 2016, Material for MkDocs has helped tens of thousands of teams to publish and maintain reliable documentation. However, in recent years, it has become apparent that we were running up against limitations of our core dependency, MkDocs. These limitations proved impossible to overcome as they are deeply rooted in its architecture.

We also mentioned in our update on our foundational work that MkDocs must be considered a supply chain risk, since it's unmaintained since August 2024. It has seen no releases in over a year and is accumulating unresolved issues and pull requests. These developments have forced us to cut our ties to MkDocs as a dependency.

In order to map out a path forward, we went back to the drawing board, talked to dozens of our professional users and thoroughly analyzed the MkDocs ecosystem. We didn't just want to create a fork or port of MkDocs, but decided to rethink static site generation from first principles.

With Zensical, we are creating a modern static site generator, which is compatible with your content and customizations, and addresses MkDocs' limitations. While Material for MkDocs is built on top of MkDocs, Zensical consolidates both projects into one coherent stack, covering static site generation, theming, and customization. What you can expect today:

• 5x faster rebuilds
• Modern design
• Blazing-fast search

Although we haven't reached full feature parity yet, you can already use Zensical to build your existing Material for MkDocs projects with minimal changes.

You can jump to the compatibility section to learn what is already supported.

What you can expect

Solid foundation

Our goal with Zensical is to create a coherent and modern stack, vertically integrating all parts of the authoring experience (AX), developer experience (DX), and user experience (UX). This gives us a significant competitive advantage over solutions that overly rely on third-party frameworks and dependencies, helping us to create much more robust Open Source software.

ZRX, our new differential build engine, creates a solid foundation for Zensical, and is an Open Source project of its own. It's a fresh take on making differential data flows easy to build and a joy to work with. Most engineering effort has gone into ZRX, as it forms the backbone of Zensical, and will allow us to ship features faster.

Following the principle of architectural hoisting, we moved essential, reusable functionality into ZRX, which allows us to keep Zensical's core simple and focused on static site generation. ZRX handles the heavy lifting – differential builds, caching, and data flow orchestration.

With the upcoming module system and component system, both of which are on our public roadmap, Zensical will gain more degrees of freedom in the coming months, allowing you to extend and customize Zensical in ways that were previously impossible with MkDocs.

Modern design

Zensical brings a fresh, modern design that breaks out of the Materal Design aesthetic, creating a visual foundation that is more easily brandable and adaptable to different use cases. The new design prioritizes clarity, simplicity, and usability, while having a more professional finish:

Our public roadmap, built with Zensical

Right now, the layout and site structure of Zensical match Material for MkDocs closely, as we're focusing on ensuring maximum compatibility. Once we finish work on our upcoming component system, we'll provide an alternative that is much more flexible and adaptable, and can be tailored to different use cases and branding requirements more easily.

You can also keep the Material for MkDocs look and feel with a single line of configuration.

Blazing-fast search

Client-side search isn't a compromise – for the vast majority of static sites, it's the best solution, since it's faster, involves zero maintenance, and doesn't require you to pay for a service.

As covered in depth in the first part of this series, the current search implementation in Material for MkDocs has severe limitations, and is based on a now unmaintained library, which is why we decided to build a new search engine from scratch. It's based on the same goals as Zensical itself: performance, flexibility, and extensibility.

Disco, our modular and blazing-fast client-side search engine, is exclusively available in Zensical. When you build your site with Zensical, your users will immediately benefit from Disco's improved ranking algorithm, as well as its filtering and aggregation capabilities:

Disco on zensical.org

We'll release Disco as an MIT-licensed standalone Open Source project soon. With the feedback of our professional users in Zensical Spark, we're going to evolve the search experience, turning Disco into a highly configurable and customizable search engine that adapts to your needs.

You can subscribe to our newsletter to receive news about Disco.

Authoring experience

Slow feedback loops can be a major pain point when writing documentation. Almost all of us know the feeling of waiting for the static site generator to finish building the site, just to see a small change reflected in the output. With Zensical, we're finally addressing this issue.

It's important to understand that we're not yet utilizing the differential capabilities of ZRX to the fullest extent, as we're forced to make several compromises to ensure maximum compatibility with Material for MkDocs at the moment. Markdown rendering needs to go through Python Markdown, which forces us to pay for extra marshalling costs.

While the initial build can sometimes be slower than with MkDocs, repeated builds – especially when serving the site – are already 4 to 5x faster, as only changed files need to be rebuilt.

We're also working on a new Markdown toolchain based on a CommonMark-compliant parser written in Rust, which will make Markdown processing significantly faster. We'll be tackling this as part of the upcoming component system, which we'll start working on in early 2026. Once our new Markdown toolchain is ready, we'll provide automated tools to translate between Python Markdown and CommonMark, so you don't need to manually migrate your content.

Maximum compatibility

Compatibility with Material for MkDocs is our top priority. We understand that switching to a new static site generator can be challenging, especially for large projects with many customizations. Therefore, we've put significant effort into ensuring that Zensical understands mkdocs.yml configuration files, so that you can build your projects with minimal changes.

This means your existing Markdown files, template overrides, CSS and JavaScript extensions don't need to be touched, primarily because we did not change the generated HTML, and rely on Python Markdown for processing your content.

However, plugins are a different story. In MkDocs, practically all plugins have side effects, making it impossible to parallelize builds. We started from first principles and asked: what should extensibility look like in a modern static site generator? Our answer is the upcoming module system, which takes a fundamentally different approach based on four core principles:

• Modules can inject, extend, and re-define functionality
• Modules are deterministic through topological ordering
• Modules foster reusability, with the possibility to remix them
• Modules can cooperate through well-defined contracts

We're working on shipping essential functionality as provided by MkDocs plugins as built-in modules. In early 2026, we will open the module system to third-party developers, so they can start building their own modules, as we see Zensical as the heart of a thriving ecosystem.

Zensical Spark

Material for MkDocs was originally built for individual developers and small teams, but over the years it found its way into the workflows of large organizations and professional documentation teams – far beyond what we ever anticipated. With that came a new set of requirements: scalability, dedicated support, and a direct line to the team behind the project.

Zensical Spark is our answer to that. Rather than building software that organizations need to adapt to, we built Zensical from the ground up around the needs of professional teams – handling documentation of any size, seamlessly, out of the box.

As a Spark member, you get early access to new features, hands-on migration support, and direct access to the Zensical team. Your participation in Zensical Spark directly shapes the direction of the project, and your financial contribution ensures that we can continue to develop and maintain Zensical as a set of OSI-compliant Open Source projects.

Learn more about Zensical Spark or reach out to us at [email protected].

Zensical is built for everyone – individual developers, small teams, and large organizations alike. Zensical Spark provides you with dedicated support from the team that built Material for MkDocs for the last decade, ensuring Zensical adapts to your organization as you grow.

We're growing our team

We're also excited to announce that we're growing our team:
Timothée Mazzucotelli, also known as @pawamoy, is joining Zensical!

At Zensical, Tim is focusing on providing the same seamless experience for generating API reference documentation from source code (via docstrings) as he has done with mkdocstrings, the second biggest project in the MkDocs ecosystem. With his expertise, and Zensical's new stack, we'll be pushing the boundaries of what's possible with API reference documentation.

Goodbye, GitHub Sponsors

Thank you! To all of you who have supported us over the years through GitHub Sponsors – we are incredibly grateful for your support. It has been invaluable in helping us to build, maintain and evolve Material for MkDocs, and we couldn't have done it without you.
Seriously, thank you!

Material for MkDocs gave us something invaluable: experience building for tens of thousands of users, and the opportunity to build a team around Open Source software. It showed us that making a living from Open Source isn't just possible – we grew it into one of the largest sponsorware projects on GitHub and inspired others to pursue similar paths.

Now we're breaking new ground. Zensical is our next chapter, and we're professionalizing how we approach Open Source development. Our vision is to make Zensical free for everyone to use while building a sustainable business around it through [our new approach].

This transition means saying goodbye to GitHub Sponsors. It has served us exceptionally well, but as we professionalize and scale, we're making the leap from personal project to company – building a business and team that can meet the growing demands of professional users while staying true to our values.

We're doubling down on Open Source, developing software for everyone.

If you want to continue supporting our work, please subscribe to our newsletter. We'll be providing new methods to support us in the coming months, with the possibility of getting exclusive goodies.

Looking Ahead

Material for MkDocs grew organically like a plant in a pot that eventually became too small. With Zensical, we're building on solid foundations designed to grow with us – and with you.

Material for MkDocs is in maintenance mode

We want to be transparent about the risks of staying on Material for MkDocs or on forks of both Material for MkDocs and MkDocs. With MkDocs 1.x unmaintained and facing fundamental supply chain concerns, its future is uncertain and we cannot guarantee Material for MkDocs will continue working reliably. MkDocs 2.0 will introduce breaking changes – something we analyzed thoroughly in our MkDocs 2.0 article.

We're aware that transitioning takes time, which is why we commit to supporting Material for MkDocs for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed. If you have questions about your specific situation or need help planning a migration, don't hesitate to reach out at [email protected].

Where we'll be in 12 months

Over the next 12 months, following our phased transition strategy, we'll reach Phase 2 and 3 – introducing our module system and component system, as well as CommonMark support. By replacing Python Markdown with a Rust-based Markdown parser, we'll unlock performance improvements and the modularity needed for flexible templating. This is where Zensical truly starts to unfold its capabilities.

Zensical is already powering real projects due to extensive compatibility with Material for MkDocs. We're actively working on closing the gap to reach full feature parity.

You can install Zensical now, and build your existing Material for MkDocs projects with it. If you run into a bug, please don't hesitate to open an issue – we're here to help.

Connect with us

If you have questions we haven't addressed, please reach out to us at [email protected]. We're currently collecting questions from the community about Zensical, and will address them in an FAQ section as part of our documentation in the coming weeks.

We're incredibly thankful that you have been part of our journey so far. With Zensical, we're embarking on a new chapter, and we couldn't be more excited to have you with us.

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

Warning

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

Opened up version ranges of optional dependencies for forward-compatibility

Added warning to mkdocs build about impending MkDocs 2.0 incompatibility (doesn't affect strict mode)

Warning

Material for MkDocs is in maintenance mode

Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs until November 2026.

Read the full announcement on our blog

Changes

Updated requests to 2.30+ to mitigate CVE in urllib

Fixed privacy plugin not picking up protocol-relative URLs

Fixed #8542: false positives and negatives captured in privacy plugin

Warning

Material for MkDocs is now in maintenance mode

This is the last release of Material for MkDocs that will receive new features. Going forward, the Material for MkDocs team focuses on Zensical, a next-gen static site generator built from first principles. We will provide critical bug fixes and security updates for Material for MkDocs for 12 months at least.

Read the full announcement on our blog

This release includes all features that were previously exclusive to the Insiders edition. These features are now freely available to everyone.

Note on deprecated plugins: The projects and typeset plugins are included in this release, but must be considered deprecated. Both plugins proved unsustainable to maintain and represent architectural dead ends. They are provided as-is without ongoing support.

Changes:

• Added support for projects plugin (for compat, now deprecated)
• Added support for typeset plugin (for compat, now deprecated)
• Added support for pinned blog posts and author profiles
• Added support for customizing pagination for blog index pages
• Added support for customizing blog category sort order
• Added support for staying on page when switching languages
• Added support for disabling tags in table of contents
• Added support for nested tags and shadow tags
• Added support for footnote tooltips
• Added support for instant previews
• Added support for instant prefetching
• Added support for custom social card layouts
• Added support for custom social card background images
• Added support for selectable rangs in code blocks
• Added support for custom selectors for code annotations
• Added support for configurable log level in privacy plugin
• Added support for processing of external links in privacy plugin
• Added support for automatic image optimization via optimize plugin
• Added support for navigation paths (breadcrumbs)
• Fixed #8519: Vector accents do not render when using KaTeX

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.

Material for MkDocs終於​支持​中文​了！文本​被​正確​分割​並且​更​容易​找到。

This article explains how to set up Chinese language support for the built-in search plugin in a few minutes.

Configuration

Chinese language support for Material for MkDocs is provided by jieba, an excellent Chinese text segmentation library. If jieba is installed, the built-in search plugin automatically detects Chinese characters and runs them through the segmenter. You can install jieba with:

pip install jieba

The next step is only required if you specified the separator configuration in mkdocs.yml. Text is segmented with zero-width whitespace characters, so it renders exactly the same in the search modal. Adjust mkdocs.yml so that the separator includes the \u200b character:

plugins:
  - search:
      separator: '[\s\u200b\-]'

That's all that is necessary.

Usage

If you followed the instructions in the configuration guide, Chinese words will now be tokenized using jieba. Try searching for 支持 to see how it integrates with the built-in search plugin.

Note that this is an experimental feature, and I, @squidfunk, am not proficient in Chinese (yet?). If you find a bug or think something can be improved, please open an issue.