Nixpkgs and NixOS manual enchancmenets userscript

As everybody here is probably aware of, the current Nixpkgs and NixOS manual user experience is not ideal. While there are official solutions being worked on, it might still be quite some time until they are complete. In the meantime, I decided to implement a temporary “band-aid” solution that will improve the manual experience for now.


  • Manual split into separate pages for each section
  • Navigation through a collapsible sidebar
  • Full-text search using Orama
  • Dark mode toggle using Dark Reader

You can find more info about it as well as how to use it here: GitHub - Tomaszal/nix-manual-enhancements: Userscript that introduces some user experience enhancements to the Nixpkgs and the NixOS manuals


I may be missing something, but I can’t find a link to it…

There’s a link in the GitHub readme “installation” section (it simply links to the latest release). After installing it just open the Nixpkgs or NixOS manual like you usually would, and you’ll see the enhanced interface.

So it is a browser plugin? Not usable on mobile, where I’d need the page-per-section the most?

It works via a userscript manager, which is an add-on, yes. Firefox for Android supports add-ons, so it would be possible to make it work there. However, it does not support the ‘:has()’ selector, which is used in this userscript. I could attempt making it work without it if people are interested.

Though, just to make sure, why is the page-per-section most important on mobile for you? If it’s to save bandwidth, this will not affect that. This works by injecting some JavaScript into the manual page after it’s loaded, splitting the content by sections, and saving it to memory. So the whole manual is still downloaded.

If you want a true page-per-section experience, you’ll need to wait for something like mmdoc (Nixpkgs PR, NixOS PR). There are some demo renders which you can browse anywhere, but those are incomplete (transition to CommonMark still ongoing) and outdated as soon as there is new content in the manual (at least until the demos are re-rendered), which is why I took this approach instead.

The original manuals are crashing my phone. Regardless of the browser used.

That is very odd, but yeah, unfortunately this won’t be of any help in this case.