nixpkgs-manual-mmdoc, nixos-manual-mmdoc: init

[ryantm]

This is a prototype Markdown manual renderer that has as few dependencies as possible. We might wish to have something like this because it would limit the build closure required for building the manuals, which is most important for NixOS.

The only dependencies are:

• mmdoc - My C wrapper around cmark-gfm for making documentation
• cmark-gfm - a C implementation of the CommonMark spec with additional GitHub-flavored Markdown extensions
• xxd
• fastJson
• libzip

It uses assets from

• fuse.js
• highlight.js

Another benefit of this minimal approach is the manual can be rendered very quickly. cmark claims it can render War and Peace in 100 ms.

Try the Live demo!

Try it yourself

• Checkout this branch
• nix run .#nixpkgs-manual-mmdoc-watch
• visit http://localhost:8000/ in your web browser

[ryantm]

Some of the edits here should be removed and it should be rebased on top of #108147

[ryantm]

I've extracted the work into its own project now https://github.com/ryantm/mmdoc

[ryantm]

@ofborg eval

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nixpkgs-and-nixos-manual-enchancmenets-userscript/34203/5

[ryantm]

I plan to merge this in one week unless I get feedback on it.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-01-04-documentation-team-meeting-notes-102/37754/1

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-01-25-documentation-team-meeting-notes-106/38792/1

[infinisil]

This is being discussed a bit in the docs Matrix room

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/help-wanted-planning-for-summer-of-nix-2025/47556/2

[ryantm]

Closing this because I couldn't get buy-in from the nixpkgs documentation team to adopt a tool that is written in the C language, they'd much rather prefer to do some python thing but then never actually publish it years later I guess.