Skip to content

Plugin Support After the MkDocs Fracturing

Major Players

Sadly there has been a fracturing in the MkDocs ecosystem. As of the writing of this message (2026-05-20) and to my knowledge, the following main players exist:

  • MkDocs 1.x and Material for MkDocs. They are no longer maintained, so it is probably smart to migrate away from them in the long term.
  • Forks: ProperDocs and MaterialX. They remain mostly backwards-compatible for now and are actively supported.
  • Zensical: A new site generator from the Material for MkDocs author. Plugin support including Python is planned but not implemented yet.
  • MkDocs 2.0: Early analysis showed that it has no support for plugins.

Support for my Plugins

MkDocs 1.x

My plugins were written for MkDocs 1.x (usually 1.5.0 or later) and I do not try to break compatibility with it unnecessarily. Should it be useful in the future (for example because the forks add non-backwards compatible changes that improve performance drastically or simplify my code) then support will be dropped. If that happens (intentionally) I'll try to add a warning to the README with the last version that supports it.

Forks

I applaud the initiative, but as it is still early days it is hard to figure out if the forks work in the long term, which will be popular, etc. Due to this I'll try to remain broadly compatible, but focus will be on supporting the most popular forks (to my knowledge currently ProperDocs and MaterialX). If you are using an active fork and my plugins do not work, feel free to open an issue and I look at how hard support would be.

Zensical

The plugin API is not released and in my estimation will likely be very different from the MkDocs one. As such support depends on how popular Zensical will be and how hard support for it is. If Python plugin drops and you want a port, just open an issue in the specific plugin :)

For some plugins that do not rely on site generator specifics, like my badges plugin with just does in-place Markdown conversion or the placeholders plugin which I designed to have a site generator agnostic core library I can probably port them easily. In the meantime I can try to write you standalone versions that work as preprocessors or something similar.

MkDocs 2.x

As it likely will have no plugin support, it will not be supported.

My Actions

I plan to go over all my plugins and remove the explicit dependency on mkdocs or any of its forks. My goal is to give you the freedom to choose what fork you want to use (including staying with mkdocs 1.6.1).

Regarding the warning messages as have been employed my Material for MkDocs and ProperDocs I understand the reasoning, but I do not think I'll do it either. IMO it should be on you as the user to do proper dependency management (pinning package versions, etc) and I do not want to annoy anyone with naggy messages. Given the reach that Material for MkDocs has, I don't think my plugins will reach anyone that it did not :)