Migrate from mkdocs to something else

[benoit74]

We are using mkdocs to generate documentation of multiple projects (python-scraperlib, python-libzim, ...).

The community is moving away from MkDocs due multiple drama.

I feel like we should probably follow the community and move to ProperDocs or Zensical.

See e.g. the very opinionated input from Material for MkDocs team: https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

We should probably try to migrate a first project to what feels like the best future for our needs (and the plugins we are currently using).

[rgaudin]

I remember a discussion about this with @elfkuzco on some ticket or PR but I can't find it. @elfkuzco do you remember?

[elfkuzco]

It wasn't a ticket. I sent it as a private message on Slack. It pointed out the same thing - the collapse of Mkdocs. Here's the link I sent in the message: https://www.reddit.com/r/Python/comments/1s0gfyb/the_slow_collapse_of_mkdocs/. I brought it up because I had worked on a PR that generated documentation for libzim using mkdocs

Your response was:
"I had no idea! Well maybe a some point in the future we'll have to switch to one of its successor. thanks for the link!"

[rgaudin]

Thank you

[kelson42]

Do we have a concrete problem right now? If "yes", which one? What would be the impacts, both for devs and final users, of such a move?

[benoit74]

I don't think we have a concrete problem now, hence this issue in overview repo to bring awareness and share decisions.

As far as I've understood, the current situation is:

• mkdocs 1.x is unmaintained (last release if 2 years old)
• mkdocs is about to release 2.x which will break many plugins
• material for mkdocs will not support release 2.x ; probably multiple other plugins will do the same

We are hence at risk right now because living on obsolete tools. All versions should be pinned (they are in python-scraperlib for instance), so doc generation will not break immediately, but we are in a sort of dead end (like we will not be able to upgrade simply).

As soon as the ecosystem continues to move (e.g. Python 3.15 releases new stuff), we will start facing issues which can't be solved without upgrading.

There are two ways forward (to upgrade): migrate to mkdocs 2 or choose another tool. I'm not sure any of them will fully support our needs. At least the community seems to indicate they will not make the effort to support mkdocs 2 and rather shift to other tool.

Before migration, impact for devs and final users is that some doc will be outdated or not achieve to update anymore.

After migration, there is no significant impact for devs and final users. I do expect to have some UI changes for final users and some changes in how docs configuration is done for devs ; nothing which changes anything in daily usage of code / documentation.