You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
__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.__
21
+
__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.__
20
22
21
-
We've taken the time to thoroughly evaluate and test the pre-release version, and 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.
23
+
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.
24
+
25
+
__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.
22
26
23
27
_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._
24
28
@@ -28,79 +32,96 @@ _Please note that MkDocs 2.0 is still in pre-release, and the information in thi
28
32
29
33
## What's changing in MkDocs 2.0
30
34
31
-
Based on the [official announcement], the published [roadmap][^1], 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:
35
+
Based on the [official announcement], the published [roadmap][^1], 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:
32
36
33
37
[^1]: The published roadmap was removed on February 19, 2026. The link now points to an issue comment that contains a screenshot of the last available version of the roadmap.
34
38
35
-
-__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 wide-spread adoption, and its removal will affect workflows and customizations that teams have built over time.
39
+
-__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.
40
+
41
+
-__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.
36
42
37
43
-__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.
38
44
39
45
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.
40
46
41
-
-__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.
47
+
-__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.
42
48
43
-
-__MkDocs 2.0 has a new configuration format__– MkDocs 2.0 uses TOML for configuration, which is entirely different from 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.
49
+
-__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.
44
50
45
-
-__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 should be critically evaluated by teams and organizations that rely on MkDocs for their documentation projects.
51
+
-__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.
46
52
47
53
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.
48
54
49
-
Additionally, it's important to note that [MkDocs 1.x is unmaintained], with seemingly no plans to fix long-standing issues like [recent problems with live-reload].
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.
66
+
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.
62
67
63
68
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.
64
69
65
-
## Where Zensical comes in
70
+
??? info "How to disable the MkDocs 2.0 incompatibility warning"
66
71
67
-
This is part of [why we built Zensical], our new static site generator, designed from the start to be [a reliable, backward-compatible home] for your existing MkDocs projects.
72
+
Starting in Material for Mkdocs 9.7.2, a warning is printed during a build about the upcoming MkDocs 2.0 changes. We added this warning to ensure users are aware of the potential impact of MkDocs 2.0 on their projects, and to encourage them to evaluate their options and plan accordingly.
68
73
69
-
We've designed Zensical to be as compatible as possible with Material for MkDocs and with the broader MkDocs ecosystem. We maintain compatibility across these key areas:
74
+
To disable this warning, set this environment variable:
70
75
71
-
-[x]__Build configuration__ – Use your existing `mkdocs.yml` file. No new config format to learn, and no need to create a `zensical.toml`.
76
+
``` bash
77
+
export NO_MKDOCS_2_WARNING=1
78
+
```
72
79
73
-
-[x]__Content and front-matter__ – Python Markdown and all extensions work without changes. Your existing content builds as-is.
80
+
## We raised concerns early
74
81
75
-
-[x]__Project structure and URLs__ – Files stay where they are. URLs and anchors remain identical, preserving bookmarks, external links, and SEO.
82
+
All of this isn't coming as a surprise to us, given that the maintainer has presented his plans in an open video call [back in August 2024]. Since it was unclear whether the maintainer would follow through with these plans, we only mentioned it in a footnote, but the pre-release version of MkDocs 2.0 confirms that there will be significant breaking changes for existing projects:
76
83
77
-
-[x]__Template overrides__ – Minor adjustments for MiniJinja compatibility (already shipped in recent Material for MkDocs versions). HTML structure remains unchanged.
84
+
Here's a summary of [the timeline of events]:
78
85
79
-
-[x]__Custom CSS and JavaScript__ – Generated HTML, CSS variables, and JavaScript APIs remain compatible with your existing customizations.
86
+
> After [we raised this issue] with the maintainers of MkDocs [...], and [maintainership changed] mid 2024, work on a [ground-up rewrite] that aims to address slow reloads by [rendering only the page currently being built] has started. It's still unclear how this rewrite will integrate with the requirements of existing plugins. Complex plugins such as [mkdocstrings], or our [built-in blog] and [tags] plugins require a coordinated build of all pages to accurately resolve links between pages and to computed resources, which cannot be determined without building the entire project.
80
87
81
-
We're working hard on [feature parity], bringing support to Zensical for the most popular MkDocs plugins, and ensuring that your existing projects can be migrated with minimal effort.
88
+
> __Update__{ title="August 21, 2024" }: The new maintainer now publicly stated that he's working towards a new version of MkDocs that [does not require or support plugins], and mentions it will be equally capable through offering customization via templating, themes, and styling, which he also mentioned to us and several other users in [a team call on August 1]. In this call, [we raised objections multiple times] in regards to how this will impact the ecosystem, to no avail. No intention or roadmap for plugin support was provided. This development is orthogonal to our goal empowering users and organizations to adapt the core framework to their requirements by the means of modularity. We're working on resolving this situation, and will provide a way forward for our community.
82
89
83
-
Additionally, we're working on a much more flexible [module system], which will supersede the plugin system of MkDocs 1.x and enable you to build custom features and integrations in a more maintainable way.
90
+
The moment we learned about these plans, [we immediately started working] on what would eventually become [Zensical] – a new static site generator designed to be backward-compatible with MkDocs 1.x and a reliable long-term home for your existing documentation projects.
We considered forking MkDocs, but quickly realized it wasn't viable: every plugin in the ecosystem has a direct dependency on `mkdocs`, which means forking MkDocs would require forking every single one of its [300 plugins] – __like moving an entire city at once__.
89
93
90
-
!!! tip
94
+
With forking being impractical, we had to start from scratch.
95
+
96
+
[we immediately started working]: transforming-material-for-mkdocs.md
97
+
[the timeline of events]: transforming-material-for-mkdocs.md#fn:7
98
+
[back in August 2024]: https://github.com/mkdocs/mkdocs/discussions/3671#discussioncomment-10164237
Starting in Material for Mkdocs 9.7.2, a warning is printed during a build about the upcoming MkDocs 2.0 changes.
93
-
94
-
To disable this warning, set the environment variable `NO_MKDOCS_2_WARNING=1`.
112
+
## Where Zensical comes in
95
113
96
-
## The story behind Zensical
114
+
[Zensical][website] is designed to be a __drop-in replacement for MkDocs 1.x__, with the goal of building your existing projects without any changes. _We're not fully there yet_ – supporting the most popular MkDocs plugins in the ecosystem is an ambitious undertaking – but it's our current focus, and we're fully committed to getting there.
97
115
98
-
@squidfunk joined the [Talk Python To Me] podcast to share Zensical's origin story, why we built it from scratch, and what's ahead of us. You can watch the full episode here:
116
+
Rather than turning this into a marketing pitch, we encourage you to read the [announcement post][Zensical] if you'd like to understand how Zensical differs from MkDocs and what you can already expect today. Additionally, the [compatibility section] on our website offers an overview of what features are already supported without changes.
We also encourage you to do your own research, evaluate the implications for your projects, and consider all available options. If you've relied on Material for MkDocs professionally, valued our work, and are looking for a clear path forward, we're offering [hands-on support for migration].
103
119
104
-
This episode will soon also be available as an audio-only episode on all major platforms.
120
+
_If you have any questions, feel free to reach out to Kathi at hello@zensical.org._
0 commit comments