How to deal with MkDocs?

Hello,

TL;DR: MkDocs 1.x has been discontinued, 2.x is breaking backwards
compatibility and infuriating the community, and we have a bunch of
forks now -- how do we deal with that crap?


A while ago dev-python/mkdocs was added to Gentoo.  You know, the new
documentation system that all cool kids use because you then don't have
to use ReST but instead you do cool Markdown like all the cool GitHub
kids do.  It got quite popular, and got lots of plugins.  It's now
handled via docs.eclass.

Recently upstream discontinued MkDocs 1.x and started working on 2.x. 
This seems to have caused quite an uproar: apparently upstream not only
breaks backwards compatibility, but made some questionable changes like
removing the plugin system entirely [1].

So mkdocs-material folk has created 'Zensical' as an alternative to
MkDocs, and then someone forked MkDocs 1.x into 'properdocs'. 
Unfortunately, this fork is a true fork -- with everything renamed and
no CLI-wise backwards compatibility (I suspect it's backwards compatible
with plugins but I have no clue).

The mkdocs-gen-files plugin now requires *both* mkdocs (1.x) and
properdocs (as in RDEPEND).

Where do we go from here?

If you asked me, I have no interest in maintaining yet another
documentation system (or two), updating docs.eclass, and waiting a few
years while projects keep deciding what to switch to (or maybe create a
third fork, because it's easier to fork than to search for an existing
fork).  So I would lean towards removing mkdocs support entirely, and
last riting the whole stack.


[1] https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

-- 
Best regards,
Michał Górny

-----BEGIN PGP SIGNATURE-----

iKQEABYKAEwWIQQcFD0bEK7NPNmWHtiOMjR69AVa6AUCabj+OxsUgAAAAAAEAA5t
YW51MiwyLjUrMS4xMiwyLDISHG1nb3JueUBnZW50b28ub3JnAAoJEI4yNHr0BVro
GQsBALclzuvwJaCQqfJYqsfWyPA0+b1/f/GDFg0J4AQR5CCXAP9XbVlV1kyJ8nv+
WhDFNP+RPbhJdSiXT7a4K2jVf6soBw==
=ZNyi
-----END PGP SIGNATURE-----