Skip to content

My move to ProperDocs and why you should too

With this Blog post would I like to announce that I have moved my Website away from MkDocs and towards using ProperDocs1.
There are various reasons which I will get into, including why you should consider moving to it too, if you're still using MkDocs.

Important

This blog post contains my personal opinion.
While I'll try my best to remain somewhat objective, I'll not guarantee that this will be the case throughout the entire post.

In this post will I also address and mention lovelydinosaur.
To avoid issues of misgendering and deadnaming, am I gonna use they/them pronouns and only use their github username (lovelydinosaur) throughout this post.

Transparency Notice

  • I'm part of the ProperDocs Organisation and therefore may have a bias towards it.
    With that said am I trying to stay objective in this post regarding information shared.
  • This post will use web.archive.org links where possible for discussion links.
    This is done to preserve them, in case the original will be removed/hidden such as with my RfC discussion.

Why I moved

MkDocs has not seen any releases for nearly 2 years at this point.
For projects with little to no bugs would this not be an issue, but as the issue tracker and Pull requests of MkDocs show does the project contain various issues that aren't being addressed, some of which a lot more important than others.

This state makes MkDocs a security risk, as it can contain possible exploits, either due to bugs in its own code, or due to outdated dependencies with such exploits.
It puts a lot of danger on the end user (Possibly You!).
Further is there a lack of community interactions. Many questions remain unanswered and critiques given to the v2 (more on that in a bit) are being ignored.

Version 2

However, the most important reason was Lovelydinosaur's - The original creator and owner of MkDocs - announcement of a Version 2 of MkDocs2.
This v2 was a complete rewrite of MkDocs and contains several, non-backwards compatible changes, including, but not limited to:

  • Move from YAML to TOML
    The project now uses a TOML file instead of a YAML file. This comes not only with syntax changes, but also changed existing option structures, such as nav entry nestings.
    There exists no information regarding any possible backwards-compat for the old mkdocs.yml making it very likely that your existing configuration will no longer work.
  • Removal of Plugins API
    Plugins are probably the most important part of MkDocs, allowing you to customize its feature set beyond its default capabilities. Even this blog here is only possible thanks to the Blog plugin from Material for MkDocs!
    This unique feature of MkDocs however, was removed in v2. And lovelydinosaur has given no info in regards to any reimplementation for such support in the future, making it very likely that plugins will no longer work.
    The project seems to be primarely focused on Themes and less on extendability through plugins.
  • Breaking Theme Changes
    v2 contains changes to the theme API/system that will limit existing themes - especially Material for MkDocs - in their feature set, as it no longer provides functionality used for certain features, making them very limited.3

Due to these reasons, alongside other ones related to the project handling itself such as a questionable bug-tracking policy (Not reporting through issues but a Gitter chat instead), lack of an (open source) license and questionable actions/responses by its owner (More on that later) have I moved on to ProperDocs.

What is ProperDocs

ProperDocs is a fork of MkDocs v1, trying to maintain and update it.
The project is fully backwards-compatible with existing MkDocs configurations, including plugins and themes.

The project is actively maintained, fixing long-standing issues in MkDocs while also adding smaller QoL changes such as the separation of the default themes into their own projects, making it smaller in size.

Why you should move too

There is no guarantee that this v2 of MkDocs will receive the changes to make it compatible with existing v1 changes. In addition could this v2 drop at any given moment and replace the latest version on PyPI, meaning that when you update MkDocs through pip install -U mkdocs, that it will download v2 and with it all the major breaking changes for your project.
The only hope regarding this, is that this v2 would be published under a new project name, properly separating it from the original MkDocs.

This is the major reason why you should consider a move. This damocles sword could fall at any time and hit the community hard, destroying even more than what its abandonment so far has caused.
ProperDocs exists to try and save what is left of the MkDocs community, by providing a maintained drop-in replacement for MkDocs v1 users.

Why not Zensical?

I'm aware that Zensical, an SSG similar to MkDocs created by squidfunk, exists and seems to become popular.
However, this project lacks a lot of features I myself need to actually switch. Such features include a Plugin API that allows plugins such as the blog plugin to properly work.
The project - while promising - is simply to unstabe/unfinished for me to be considered. With ProperDocs do I have a drop-in replacement that just works.

My issues with lovelydinosaur

Info

This section is all my personal opinion and only reflects my personal views towards lovelydinosaur.
With that said is it not my intention to attack and insult them, but simply point out behaviours I have an issue with.

While I did not had many interactions with lovelydinosaur in the past, the ones I did had did make me dislike them a lot.
Not only did it become clear rather quickly that they did not care about maintaining v1 of MkDocs and instead focus solely on a v2 (not even considering to "pass the torch" for v1 to someone else), but that they seem to have an agenda regarding genders, particularely regarding ones "owned" by one gender according to them:

comment_example_1

Reply to my RfC Discussion.4

comment_example_2

Reply in the Version 2 discussion.5

Another example can be found when going through their GitHub Activity, showing an issue they have created, complaining about a project's - which they were the former owner of - name, especially related to gender, and the ownership model.

comment_example_2

Issue Post on the Starlette project.6

It's such messages that make me dislike lovelydinosaur, as it's certainly not professional.
Closing a discussion simply because you don't want conversations in an "all-male online space" (Which is blatantly not true) makes you seem sexist in all honesty. At least from my view.

Footnotes

  1. https://properdocs.org ↩

  2. https://web.archive.org/web/20260311150859/https://github.com/mkdocs/mkdocs/discussions/4077 ↩

  3. This info is based on an analyzis done by Squidfunk in regards to MkDocs v2:
    https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/ ↩

  4. Note: As of writing this are the dislikes on this reply at 12.
    https://web.archive.org/web/20260311123626/https://github.com/mkdocs/mkdocs/discussions/4088#discussioncomment-16054713 ↩

  5. Note: As of writing this are the dislikes on this reply at 3.
    https://web.archive.org/web/20260311150859/https://github.com/mkdocs/mkdocs/discussions/4077#discussioncomment-15687765 ↩

  6. https://web.archive.org/web/20260323042730/https://github.com/Kludex/starlette/issues/3180 ↩

Comments

Comment system powered by Mastodon.
Leave a comment using Mastodon or another Fediverse-compatible account.

Last update: 24. March 2026 ()