Inconsistent styling and lack of cross project navigation in Nix documentation about nix.dev

[fricklerhandwerk]

I propose the following sequence of steps:

1. Pull out the Nixpkgs and NixOS manuals out of nixos.org into nix.dev at all

   I had started this, but I have lots of higher priorities, so it won't happen in the next weeks. I can share my crufty local branch if anyone is interested in picking it up.

2. Add consistent-looking style sheets to each of the manuals.

   I was playing with the idea of doing it upstream, but this may need discussion.

   Advantages:

   • Building locally will give you the same result as you'd observe hosted online. Currently this is only the case for the Nix manual, for the reason that there is no styling applied whatsoever.
   • Allows working on style issues independently, since the build setups differ for the current three officially documented projects. There may be more in the future, and keeping those custom information downstream will likely add friction.

   Disadvantages:

   • Duplicates some styling code across projects, with a risk of going out of sync
   • Requires backporting the style additions to all actively supported versions.

Side note: I'm really not a fan of mdBook, it's not very mature compared to e.g. Sphinx. And while that sort of works, I'm not a big fan of Sphinx either. All these static site systems are too simple-minded for our use cases and need hacks and customisation. And highly bespoke usage is really problematic because it tends to be brittle and undocumented, but we need our docs infrastructure to be both powerful and low-tech while meshing with the Git/GitHub workflow.

By low-tech I mean:

• Commonplace

  Example: CSS instead of some specialist frameworks

• Straightforward handling

  If you need editor integration to make meaningful contributions, it's too hard to use

• Small stack

  Learning multiple technologies to be able to manipulate the setup is too much of a barrier. We already impose Nix, Git, Markdown, and all sorts of other random things on contributors.