What MkDocs 2.0 means for your documentation projects - Material for MkDocs Skip to content<br>– A modern static site generator built by the Material for MkDocs team

Initializing search

squidfunk/mkdocs-material

Social cards

Changelog

Setup

Plugins

Reference

Insiders

Community<br>Guides

Blog

Categories

What MkDocs 2.0 means for your documentation projects&para;<br>Last update: April 13, 2026 – see update log.<br>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.<br>Material for MkDocs depends on MkDocs as its underlying framework and central dependency. We maintain Material for MkDocs, but we have no control over MkDocs itself.<br>We've taken the time to thoroughly evaluate and test the MkDocs 2.0 pre-release and want to share our findings, including 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.<br>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.<br>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 keep it updated as we learn more.<br>This is the fifth article in a series:<br>Transforming Material for MkDocs<br>Zensical – A modern static site generator built by the creators of Material for MkDocs<br>Material for MkDocs Insiders – Now free for everyone<br>Goodbye, GitHub Discussions<br>What MkDocs 2.0 means for your documentation projects<br>What's changing in MkDocs 2.0&para;<br>Based on the official announcement, the published roadmap, and several prior comments and statements from the project's maintainer, MkDocs 2.0 is intended as a ground-up rewrite of the project to reduce complexity – and it comes with some important trade-offs:<br>MkDocs 2.0 is incompatible with Material for MkDocs – If your documentation is built with Material for MkDocs, it will cease to work with MkDocs 2.0. Material for MkDocs makes extensive use of the templating and plugin systems of MkDocs 1.x, and the changes that MkDocs 2.0 introduces are not backward-compatible.

MkDocs 2.0 won't have a plugin system – MkDocs 2.0 is being rewritten with a focus on theming, deliberately removing plugin support to simplify the codebase. We believe the plugin ecosystem is one of the cornerstones of MkDocs' success and widespread adoption, and its removal will affect workflows and customizations that teams have built over time.

MkDocs 2.0 brings breaking changes for themes – MkDocs 2.0 comes with a completely rewritten theming system. For instance, navigation is passed to themes as pre-rendered HTML rather than structured data. This makes it technically impossible to implement features like navigation tabs, collapsible sections, and other advanced navigation patterns.<br>It also limits how navigation can be styled in themes, since the HTML of the navigation cannot be adjusted to fit the theme's structure and design.

MkDocs 2.0 has a closed contribution model – MkDocs 2.0 moves to a "maintainer-driven issues" model, where community members are asked not to open issues or pull requests, and "feature requests are generally not accepted". It's unclear how users should report bugs or seek fixes when they encounter problems.

MkDocs 2.0 is currently unlicensed – MkDocs 2.0 doesn't specify a license, which has implications for how it can be used and contributed to by the community. It's unclear what the rationale behind this decision is, but it should be critically evaluated by teams and organizations that rely on MkDocs for their documentation projects.

MkDocs 2.0 has a new configuration format – MkDocs 2.0 uses TOML for configuration, which is incompatible with the YAML format used in MkDocs 1.x. As a result, existing mkdocs.yml files will currently not work with MkDocs 2.0. There is no migration path for existing projects.

A release date has not been announced, so planning around a specific timeline remains difficult. However, the direction of travel has been hinted at by the maintainer on several occasions, and the pre-release version already confirms the impact of these changes on existing projects.<br>What this means for you&para;<br>It's worth paying attention: the long-term direction of MkDocs is shifting in ways that diverge from how many documentation teams – and their tooling – currently operate.<br>While your existing MkDocs projects should continue to work today, be aware that future updates to MkDocs 1.x are unlikely. MkDocs 2.0, in its current form, is not a drop-in replacement for MkDocs 1.x, and does not provide a clear migration path for existing projects.<br>How to...