Our continuation of MkDocs and a warning regarding "MkDocs 2.0"

[oprypin]

Hello, MkDocs community!

You may know me as the previous (last active) maintainer of MkDocs.

I welcome everyone to our continuation from where MkDocs was left off, named ProperDocs. You can already install it and use it as a drop-in replacement for MkDocs.

We need your support! Spread the word, come say hi, bring relevant issues to our attention!
Plugin authors can also help us further spread this warning to users. (See more info at the bottom of the post)

Why this was necessary

Sadly, at the moment MkDocs is completely unmaintained. The original author has been holding control of the project for the last 2 years while completely disregarding all feedback and all incoming issues. Offers to take over maintenance have been ignored too. They also openly state that there is a gender preference in place, leaving everyone very puzzled.

But that's not even the worst part. Their latest plan is to reuse the project's name and publish an entirely new documentation generator under it. This will break support for all themes and plugins that were made for MkDocs, with no alternative provided. Community feedback has not been welcomed.
So, by using pip install mkdocs, you are subjected to an ongoing gamble as to if/when this breakage happens.

Solution for users

We welcome you to switch to ProperDocs, our carefully crafted fork of MkDocs. At the moment it is an exact drop-in replacement for MkDocs, only with a few most critical bug fixes added. In the future you can of course expect further development.

Note

If you don't appreciate our warning that appeared when running mkdocs on the command line, you can disable the warning directly - by setting the environment variable DISABLE_MKDOCS_2_WARNING=true NO_MKDOCS_2_WARNING=true.

Here's how to get started:
(or if you're a new user, just start with https://properdocs.org/ directly.)

1. Replace the dependency

If you have mkdocs as a dependency, please replace it right away:

• Before: pip install mkdocs mkdocs-foo-plugin
• After: pip install properdocs mkdocs-foo-plugin

Note that plugins should remain under their existing name even if they contain "mkdocs" in the name. They will work as is, and plugin authors don't need to create a new renamed project just for this.

2. Replace the command

• Before: mkdocs build
• After: properdocs build

(fully equivalent command line in all cases, no changes other than the command's name).

3. Optional followups

The program will remind you about these followups itself, but here they are as well:

You are welcome to rename your configuration file from mkdocs.yml to properdocs.yml, but you don't have to.

If you are using the themes "mkdocs" or "readthedocs", they have to be additionally installed. We took this opportunity to exclude them from the default installation to make it lightweight. This is the only change that could be called a breaking change.
(As such, currently there is no default theme at all. Contributions particularly welcome.)

Technical background

It was long believed that a fork is not feasible due to how every plugin depends on mkdocs directly, and I certainly believed this myself, but I realized that it's possible to overcome these issues. Unfortunately the realization came only very recently.

For plugin authors

We ask all plugin authors to join our effort.

Note

We explicitly do not ask you to break the users of MkDocs who still remain, and there's no need to do any migration that leaves only ProperDocs working. In fact, you shouldn't do anything at all, your plugin already works under ProperDocs in addition to MkDocs.

What we need is to spread the word. A plugin should do this:

1. Edit your dependencies:

   Change from mkdocs >=1.2.3 to mkdocs >=1.2.3, <=1.6.1
   AND add properdocs as an additional dependency.

   Limiting the dependency on mkdocs is needed in order to prevent an unpredictable future release from breaking both the users and our last resistance point. 1.6.1 is the last known release.

   And adding properdocs just enables the next step. The doubled dependency is a bit of a waste, but we will be in a situation where almost everything pulls in mkdocs anyway, for a very long time.

2. In the main file of your plugin (__init__.py or wherever the main class is defined), add the following code in the outermost scope:

   import properdocs.replacement_warning
   
   properdocs.replacement_warning.setup()

   This will cause a warning to be produced at the start of any mkdocs build invocation whenever at least 1 participating plugin is involved.

   Alternatively, you're free to print some warning differently in your own way. Check out our implementation: https://github.com/ProperDocs/properdocs/blob/master/properdocs/replacement_warning.py

[oprypin]

For plugin authors

Example pull request to follow in order to spread this warning to more users:

• Warn when this plugin is being used from the mkdocs executable oprypin/mkdocs-literate-nav#39

Please reference this issue when creating a pull request for your plugin:

• Tracking issue for plugins that add a warning supporting ProperDocs #41

[jaywhj]

As a former user and beneficiary of MkDocs, I will also do my part and fully support ProperDocs.

Starting from late last year, I have been maintaining MaterialX, a continuation of Material for MkDocs.
I have released several new versions so far, adding many new features and fixing a large number of long-standing bugs.
Changelog

Everyone is welcome to give it a try.

Moving forward, I will gradually update all MkDocs-related content and dependencies in MaterialX to ProperDocs.

Let’s work together!

[Wcowin]

It looks good, material corresponds to mkdocs, materialX corresponds to ProperDocs

[oprypin]

Thanks for your support @jaywhj 😊

You can update documentation to mention it, but you don't have to update dependencies 😊
That's because by default everything made for mkdocs also works with properdocs, but if you start changing the dependencies, it will stop working for mkdocs

[Andre601]

I agree.
MaterialX should for now still support MkDocs. Properdocs can/should only be included rn for the warning to send, which is something we recommend to do here.
That way can people still using MkDocs find out about the alternative.

[Wcowin]

The secret to ensuring a building does not collapse lies in laying a solid foundation. A series of recent events has been painful, leading me to switch from mkdocs to zensical. I still look forward to the future development of ProperDocs and materialX.

[jaywhj]

Sorry, I probably didn't make myself clear.

What I mean is to replace all references to MkDocs wherever possible, such as in the documentation or usage instructions.

The dependencies in the code will not be modified, so existing stability and compatibility will not be broken.

[nejch]

Some of us maintain downstream themes using the extends mechanism, with our own bundled plugins, dependencies and roadmaps for migrating from MkDocs. The proliferation of warnings pulling users into different directions might be a little confusing for our users (there are now at least two in our case).

If anyone else is in the same situation, you can add the following to your theme's (or plugin's) __init__.py so that users don't have to bring their own env vars:

import os

if not os.getenv("NO_MKDOCS_2_WARNING"):
    os.environ["NO_MKDOCS_2_WARNING"] = "true"

Note - I'm not personally invested in the current MkDocs ecosystem debate so no hard feelings, I just want to have a smooth transition without confusing the 3k+ internal projects that use our theme.

[nejch]

All good, no worries! It's just that users might want to migrate a certain way but as we pin and manage dependencies on the theme side because of overrides, it's something we want to control ourselves in certain scenarios, and it's not really something our users can solve on their own. So just wanted to add a workaround for people in my situation.

Re: different messages, I was referring to this:

$ uv run mkdocs serve

 │ ⚠ WARNING – MkDocs 2.0 is incompatible with Material for MkDocs
 │
 │   MkDocs 1.x is unmaintained. We recommend switching to Zensical, our
 │   new static site generator, as soon as possible. We're providing an
 │   analysis of the situation in this article:
 │
 │   https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

----------------------------------------------------------------

WARNING: MkDocs may break support for all existing plugins and themes soon!

The owner of MkDocs has completely abandoned maintenance of the project, and instead is planning to publish a "version 2" which will not support
any existing themes, plugins or even your configuration files. This v2 may eventually replace what you download with `pip install mkdocs`,
suddenly breaking the build of your existing site.

To avoid these risks, switch to ProperDocs, a continuation of MkDocs 1.x and a drop-in replacement that supports your current MkDocs setup.
Simply install it with `pip install properdocs` and build your site with `properdocs build` instead of the MkDocs equivalents.

For more info visit https://github.com/ProperDocs/properdocs/discussions/33 and https://properdocs.org/

(This warning was initiated by one of the plugins that you depend on.)

----------------------------------------------------------------
INFO    -  Building documentation...

[oprypin]

Oh I wasn't familiar with all the variations of the message from mkdocs-material, I just saw that the current one doesn't seem to immediately recommend Zensical
https://github.com/squidfunk/mkdocs-material/blob/199e31598055d5d6ea538618804c7558f5d81047/material/plugins/__init__.py#L29

But of course (call me biased but) only one of these is a practical suggestion in many cases.

[Andre601]

I would like to add two points:

1. Squidfunk just released an update that doesn't print this warning on non-mkdocs forks, meaning if the software isn't called mkdocs, then it shouldn't print this warning (At least from what I understand here).
2. The warning of ProperDocs is optional. No theme or plugin dev is required to add it and by default would it not be shown if no used theme/plugin triggers the necessary command.
   Of course, there still can be such a warning, if a dev decides to add it, but I wouldn't say it's a major issue here per se.

[oprypin]

The update of mkdocs-material is interesting news. What the change causes:

• Disabled the warning from mkdocs-material when running on properdocs (nice)
• Disabled the warning from properdocs when running on mkdocs (kinda defeats my whole system)

Maybe the intention was positive though 🤷
I left the comment there squidfunk/mkdocs-material@51d9b76#diff-faabee6abf45d85b719f02e6c0c55a287bfb265b9afddeda04514aa79ba7d911R59

[oprypin]

We had to use another name for the environment variable, so the suppressions will need to be updated 😢
https://github.com/ProperDocs/properdocs/releases/tag/v1.6.7

[timo-reymann]

Just wanted to chime in here and emphasize that mkdocs is also heavily used by everyone relying on TechDocs in Backstage. See this issue, where ProperDocs is highlighted as a safety net for the community.

I sincerely appreciate the effort to keep the work on mkdocs viable through ProperDocs, and for what it’s worth, I’ve already adopted it for the two mkdocs plugins I maintain:

• mkdocs-kroki-plugin
• mkdocs-decision-records

[Guts]

The Mkdocs RSS plugin is compatible with ProperDocs since its version 1.18.0. https://github.com/Guts/mkdocs-rss-plugin/releases/tag/1.18.0

[Guts]

For now, I think it’s enough to leave it at that. And as I’ve already told the Material for Mkdocs / Zensical team, I’m not a big fan of alarmist warnings.

I’d rather see how things evolve with ProperDocs and to what extent it will go well in terms of community engagement and the quality of discussions.

Thanks you for taking the initiative to create a fork.

[oprypin]

as I’ve already told the Material for Mkdocs / Zensical team, I’m not a big fan of alarmist warnings.

Well that's how the matter is:

There is always an alarmist warning that leads people to a blog post that recommends only Zensical and still to this day says that it's impossible to make a fork.

So the only thing we can do to combat that misleading warning is to also show people that there is in fact a continuation of MkDocs that they can trivially switch to and get this over with.

[oprypin]

I’d rather see how things evolve with ProperDocs and to what extent it will go [...]

This is a two-way effect. If there isn't anyone to help out and spread the word about ProperDocs then how can it go anywhere

[Guts]

Actually, I see both warnings in CI build: https://github.com/geotribu/english-blog/actions/runs/24244584592/job/70787424290#step:6:46

[oprypin]

That's from another plugin then. (One that is mentioned in #41)

I'm just saying would be nice to add your plugin to the roster of plugins that cause this to be printed

[vedranmiletic]

Thanks for forking MkDocs and keeping it alive. I migrated our site per instructions without issues.

As a way of saying thanks, I updated the old GitHub Action guide for MkDocs to the new guide for ProperDocs (and Zensical).

[cp-elektronik]

I recently switched from Mkdocs to Properdocs having some issues with Mkdocs on Linux Mint, now everything is fine, works like a charme!
Thank you so much for taking care of this project and keeping it alive!

[sadiepowell]

I'm happy to switch to a maintained fork but I have to wonder if this fork is maintained either given the last substantial commit to ProperDocs was in March. Do you have plans for fixing the bugs that have been ignored in MkDocs?

[oprypin]

My activity is in response to issue activity. I'm not an active user myself so I need to know what needs users have.

At the moment everything works as far as I'm aware and all obvious issues were fixed. So where should the commits come from?