Documentation: mkdocs is set for a breaking change. Time to move on?

Hello, I came across this library due to it deciding to build from source (just NixOS things), and noticed that it using mkdocs in the documentation workflow.

I hate to be the bearer of bad news, but mkdocs (imo) is currently imploding due to an upcoming v2 release which breaks all plugin compatibility (your workflow also seems to depend upon mkdocs-material, mkdocs-git-revision-date-localized-plugin, and mkdocs-mermaid2-plugin). At the very least, mkdocs-material is now in maintenance mode, and are creating a new system from the ground up.

With this in mind, it is probably worth considering a migration to an alternative. I am planning on the same for many of my projects, and so am happy to share my current knowledge of the options.

• ProperDocs is a fork of mkdocs@1, which should maintain plugin compatibility. Plugin authors are encouraged to support it explicitly, but it does work without explicit support from plugin authors (if you don't mind having a heavier dependency tree).
• mkdocs-materialx as a replacement for mkdocs-material, which should be compatible with properdocs.

Other options such as Fumadocs (JS ecosystem alternative), or Zensical (rewrite linked above) would probably require a much more-complex migration process.

Start with .github/workflows/docs.yml and review its mkdocs, mkdocs-material, mkdocs-git-revision-date-localized-plugin, and mkdocs-mermaid2-plugin dependencies. Compare the ProperDocs, mkdocs-materialx, Fumadocs, and Zensical options described in the issue, including migration impact. The issue does not define a target option or acceptance criteria, so done would require agreeing on the migration scope first.