Our continuation of MkDocs and a warning regarding "MkDocs 2.0" · ProperDocs · Discussion #33

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.

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.

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