upgrade to proper-docs (with MaterialX theme) or zensical? #18

Activity

1. shenxianpeng commented on Apr 20, 2026

   

   shenxianpeng

   on Apr 20, 2026

   Member

   More actions

   After reading this post https://fpgmaas.com/blog/collapse-of-mkdocs/ what can I say...

   Maybe zensical is better than others. I'd like the "wait and see" if the future of MkDocs will continue, seems there's no immediate risk that our docs site
2. shenxianpeng commented on Apr 27, 2026

   

   shenxianpeng

   on Apr 27, 2026

   Last edited by shenxianpeng

   Member

   More actions

   I took a look at the existing community-maintained options like proper-docs... I feel it may be better to maintain this ourselves.

   So I have re-published MkDocs and Material for MkDocs under new package names:

   • mkdocs-ng
   • mkdocs-ng-material

   The commands remain the same. The only requirement is to change the dependencies to the new package names.

   Don't promise new features, but will keep the projects alive by fixing bugs, updating dependencies, and handling version upgrades and also review and accept pull requests from others.
3. 2bndy5 commented on Apr 27, 2026

   

   2bndy5

   on Apr 27, 2026

   Last edited by 2bndy5

   ContributorAuthor

   More actions

   I feel it may be better to maintain this ourselves.

   I had a similar notion. But my idea is more complex: Write my own static site generator (in rust) that supports rST and/or MD as doc inputs. The zensical theme is its own separate repo (MIT licensed), so I thought I'd render the html using those jinja templates. Basically go the same route as zensical, except mimic sphinx instead of mkdocs.

   My frustration with sphinx

   Some new admin took over sphinx a few years ago, and they have made a lot of breaking changes to its API. So many changes, that they started pinging community leaders for RC testing. These API changes are straining a community of open source devs built around sphinx. I feel like sphinx is quietly abandoning the community that has been supporting it for over a decade.
4. shenxianpeng commented on Apr 28, 2026

   

   shenxianpeng

   on Apr 28, 2026

   Last edited by shenxianpeng

   Member

   More actions

   I had a similar notion.

   We have the same feeling and the willingness to write/maintain good things.

   I assume you mentioned someone who's comment always has a letter "A" at the end :)

   And just checked Sphinx, it hasn't had any code changes for 4 months.
5. 2bndy5 commented on Apr 28, 2026

   

   2bndy5

   on Apr 28, 2026

   Last edited by 2bndy5

   ContributorAuthor

   More actions

   someone who's comment always has a letter "A" at the end :)

   Yep. But they (he?) have enablers too (like "yes-men").

   ... Sphinx, it hasn't had any code changes for 4 months

   Yea sphinx v8 and v9 pretty much broke my will to carry the sphinx-immaterial theme forward. When they go silent like that, I usually get to breathe. Now I'm working on a Sphinx replacement written in rust (with a lot of help from AI).

   Something else I've been quietly working on with AI

   It will be a new git GUI app...

   
6. shenxianpeng

   closed this as completedin #20on Oct 9, 2026