Use mdbook for site

[roberth]

Should be feasible as the options generation is already using pandoc instead of docbook's own tooling. Wouldn't mind doing more ugly stuff either, if necessary.

[srid]

I'd shamelessly plug Emanote 😁 but mdBook is a fine choice as well.

[roberth]

I thought of mdBook because it appears to have some momentum. I've been using mostly antora (advanced asciidoc) in recent times.

I'm inclined to go with something simple. I like mdBook's search capability and minimalist look. Not having search is probably a dealbreaker because I want to categorize the options by repo, yet still have a search capability for all of them together.

[zimbatm]

@roberth feel free to steal https://github.com/numtide/devshell/blob/master/modules/modules-docs.nix . It should work with any module system. Just import it and then access config.modules-docs.markdown to get the modules documented as markdown.

Here you can see how it's plugged with the rest of mdbook: https://github.com/numtide/devshell/blob/fc7a3e3adde9bbcab68af6d1e3c6eb738e296a92/default.nix#L34-L43

[roberth]

@zimbatm Thanks!

For now the docs are in docbook, which is kind of the standard for the module system. I'd like to migrate all module system applications to either markdown or something flexible and I figured my current solution might provide some of the ingredients for that. Here's my secret plan NixOS/nixpkgs#175586.

[zimbatm]

😅 How to succeed in two easy steps. Step 1) Submit a refactor PR to nixpkgs. Step 2) Success!

[roberth]

Done in #68