Our Continuation of MkDocs

Source: Hacker News

Introduction

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, and 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, leaving everyone very puzzled.

Their latest plan is to reuse the project’s name and publish an entirely new documentation generator under it. This would break support for all themes and plugins 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 critical bug fixes added. Future development is planned.

Note
If you don’t appreciate the warning that appears when running mkdocs on the command line, you can disable it by setting the environment variable DISABLE_MKDOCS_2_WARNING=true or NO_MKDOCS_2_WARNING=true.

1. Replace the dependency

If you have mkdocs as a dependency, replace it:

# Before
pip install mkdocs mkdocs-foo-plugin

# After
pip install properdocs mkdocs-foo-plugin

Plugins keep their existing names even if they contain “mkdocs”. They will work unchanged, and plugin authors don’t need to rename projects.

2. Replace the command

# Before
mkdocs build

# After
properdocs build

The command line is fully equivalent; only the executable name changes.

3. Optional follow‑ups

The program will remind you about these, but here they are:

• You may rename your configuration file from mkdocs.yml to properdocs.yml, but you don’t have to.
• If you use the themes “mkdocs” or “readthedocs”, they must be installed separately. This is the only breaking change; currently there is no default theme.

Contributions of new themes are especially welcome.

Technical background

It was long believed that a fork was not feasible because every plugin depends on mkdocs directly. I realized that it is possible to overcome these issues, but the realization came only recently.

For plugin authors

We ask all plugin authors to join our effort.

Note
We do not ask you to break users of MkDocs who remain on the original project, and there is no need to migrate in a way that leaves only ProperDocs working. Your plugin already works under ProperDocs in addition to MkDocs.

What we need is to spread the word. A plugin can help by:

1. Editing its dependencies:

   # Change from
   mkdocs >=1.2.3
   # to
   mkdocs >=1.2.3,