This is a userscript that introduces some user experience enhancements to the Nixpkgs and the NixOS manuals.
| Nixpkgs, light | NixOS, dark, search |
|---|---|
 |
 |
- Manual split into separate pages for each section
- Navigation through a collapsible sidebar
- Full-text search using Orama
- Dark mode toggle using Dark Reader
- Install a userscript management browser extension (tested with Tampermonkey).
- Open the nix-manual-enhancements.user.js file in the latest release.
- The userscript manager should appear, where you simply need to click "Install".
- IMPORTANT (Firefox only): enable
layout.css.has-selector.enabledflag inabout:config. - Done! Enjoy the manual enhancements.
Nixpkgs and NixOS offer very extensive manuals which contain a great amount of knowledge about the software. Unfortunately, those manuals have a lackluster user experience, simply presenting everything as one large, difficult to browse document. While there have been many failed and ongoing attempts to address this issue, there is still no official solution. So, as a temporary fix, I created this userscript, which is a "band-aid" solution that should be good enough until the official documentation is converted into a better format. Once that is done, this userscript will be archived and deprecated.
Historical resources relevant to this issue:
- Discourse - Better navigation of nixos.org manuals
- Discourse - Documentation improvements
- Discourse - Documentation format
- Discourse - Discourse - Documentation presentation (navigation)
- Discourse - RFC 0072 FCP, Switch to CommonMark for documentation
- Discourse - Any consensus on documentation generation tool for nixpkgs manual?
- Discourse - Dark mode on builtin nix docs
- PR - [RFC 0064] New Documentation Format for nixpkgs and NixOS
- PR - [RFC 0072] Switch to CommonMark for documentation
- PR - nixpkgs manual in CommonMark using sphinx+myst and jupyter-book
- PR - Vacation PR: multi-paged, styled, searchable docs with wrapper tooling and epubs for NixOS and Nixpkgs
Current resources to track regarding the current plan to resolve the issue: