Re: How to deal with MkDocs?

On Tue, Mar 17, 2026 at 08:09:47AM +0100, Michał Górny wrote:
> 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.

I'd say go for that, imho there isn't enough usage in ::gentoo to be
worth that much trouble (only 10 packages at a glance).

If users/maintainers really need the documentation, we always have the
option to add pre-generated tarballs until the situation/options
improve.

> 
> 
> [1] https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/
> 
> -- 
> Best regards,
> Michał Górny
> 



-- 
ionen

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

iQFPBAABCAA5FiEEx3SLh1HBoPy/yLVYskQGsLCsQzQFAmm5DlgbFIAAAAAABAAO
bWFudTIsMi41KzEuMTIsMiwyAAoJELJEBrCwrEM0SXsIALAg4Yjd4T/VFIRipG+R
3OVdItz8bNU1VbPOcNXrAqx0+BR6P9ppfgGRtO4p5VVL5Q8SM6eimDbvWAB716bS
LW5Mfj3/Z+v22tzI3Qz/mqVH7ffyCzsGtwTG/xCOSjEYYdpeicWtLXFtH12/kC+V
4xFPDLEBK04Xrs068+SsF5nwvlf99AA8Su3sfbDDrf4f4TG1vKWZd1GkHCH5Pat+
h9remIuyzY1ui74Grr4lhUgF4m7nxj0F7Bb+Y9lhsqaH9WVVG+k2dJ7iK7D/pjai
RRcO/3NMSbUgPWFSEFU/65B0AA+MWnXfDZ2rlrrFMqkoHRR1RlGYGJrgjTcorgNt
PHc=
=h6cl
-----END PGP SIGNATURE-----