The last active MkDocs maintainer forked the project as ProperDocs, a drop-in replacement, warning that an incompatible “MkDocs 2.0” may break all existing themes and plugins.
Key Takeaways
Install via pip install properdocs; replace mkdocs build with properdocs build; config file mkdocs.yml works as-is.
The original MkDocs author (Tom Christie) retains PyPI control and plans to publish an entirely new generator under the mkdocs name, breaking all existing plugins and themes.
Plugin authors should pin mkdocs >=x.y.z, <=1.6.1, add properdocs as a dependency, and call properdocs.replacement_warning.setup() to surface warnings during mkdocs build.
The only breaking change in ProperDocs vs MkDocs: built-in mkdocs and readthedocs themes are no longer bundled and must be installed separately.
Set NO_MKDOCS_2_WARNING=true to suppress the CLI warning ProperDocs injects.
Hacker News Comment Review
Commenters flagged this as a repeat open-source governance dispute; the fork author’s criticism targets Tom Christie (original author, copyright holder), which some find legally and socially fraught.
Discussion links back to a prior HN thread from March, suggesting the situation has been simmering for months with little resolution.
Notable Comments
@kstrauser: Notes the fork post calls Christie “not qualified” for maintainership despite him being the original author and copyright holder, framing this as a governance legitimacy problem.
