Which syntax feature were you trying to add?
inline roles, eg {manpage}`nix.conf(5)`.
can we have a .info for opening on emacs as well? guix has that and it so lovely being able to use emacs for guix documentation
1 Like
@ryantm why is closure size an issue for nixpkgs doc but not for nix doc?
I like about mmdoc is that it generates single and multi page documentation.
I think a few useful things are not part of mmdoc:
footnotes
footnotes[^examplefn]
(partial) file inclusion
like in mdbook: mdBook-specific features - mdBook Documentation
mermaid diagrams
example: GitHub - NixOS/nix-book: Nix documentation – centralized community online learning resource for Nix
Definition List
term
: definition
(good for glossary)
Strikethrough
The world is flat.
to be able to write down mistakes without confusing tired readers
Task List
- parse markdown
- add task lists
and maybe less important:
Subscript: H~2~O
Superscript: X^2^
[^examplefn]: footnotes are helpful
to add additional information
and references.
pandoc implements two styles Pandoc - Pandoc User’s Guide
For nix and nixpkgs manuals, the build closure size is not as important. For the NixOS manual is it is, because we build the manual as part of realizing the system (nixos-rebuild). If the user adds their own NixOS module options, they show up in the manual. Currently the manual is built by default on all NixOS systems. If we chose to optionally build it, then the closure size would be less important.
mmdoc has Definition Lists. We should be careful about adding a bunch of extensions on top of CommonMark, since that moves us spiritually farther away from the documentation format RFC, and also makes it less likely we can easily port the manual to a different backend.
1 Like
agreed, but we should also not decrease the quality of documentation output. so far we’ve been trying to introduce only the minimal set of extensions necessary to keep current docs rendering the same (where the manpage notably makes more distinctions than the html manual). adding an extension for everything docbook offers won’t do, but a few (on top of what we already have) should be okay.
how about … string processing in Nix
at least yarn.lock can be parsed with nix
ryantm started a markdown compiler in C in
Find a way to reference NixOS options in CommonMark · Issue #127813 · NixOS/nixpkgs · GitHub
I did some of that recently for Nix documentation, and if you have a faible for writing string processing standard libraries first - sure, go ahead and upstream it somewhere while you’re at it. But other than that, it’s quite unexciting (some would say painful).
that would require a markdown parser written in nix. which, like, no
you’re of course free to attempt it, but we’d rather not waste our time like that (especially since the end result would require recursive nix or IFD to be useful)
3 Likes
we’ve started work on a(nother) dedicated renderer, nixos-render-docs, since none of the existing options seemed amenable to both use in nixos manual build closures and adding the extensions that define nixpkgs-flavored markdown. this tool should totally not be considered the be-all-end-all (if it gets merged, which hasn’t happened yet!), but we’re reasonably confident that it’ll be extensible enough to add e.g. add the great html rendering of mmdoc.
4 Likes
Can you describe a little more what this means?
1 Like
nixpkgs markdown includes a number of extensions that are varying degrees of hard to add to existing markdown parsers. inline extensions like heading ids are easy enough to add to any parser with at worst a bit of fiddling, but block extensions (definition lists in particular) can be hard or even impossible. as with normal lists it’s easy to construct definition lists with paragraps that look like code blocks to an otherwise unmodified commonmark parser (due to the 4 spaces rule).
mistune, the parser we started out with for md conversions, was not extensible enough for nixpkgs markdown. we tried to add extensions to the mmdoc parser and gave up on it after a good while (now very convinced that docs processing in C is not maintainable in the long term). many rust parsers have similar restrictions.
so instead we went for markdown-it-py, which is not only very easy to extend, but also comes with a number of plugins for most of the extensions used in nixpkgs! it’s also the basis of the official myst parser (from which nixpkgs has borrowed a few extensions), so maintenance should be assured for the future.
3 Likes
status update: html rendering is mostly ready, just needs some more review. it’s fast enough that once docbook goes away (so probably for 23.11) it might even be worth considering enabling documentation.nixos.includeAllModules by default.
3 Likes