Better navigation of manuals

I was navigating the Nixpkgs manuals lately, and a couple of tweaks came to mind that would make navigation a lot easier:

  • Have a table of contents static sidebar thingy, à la Rust book
  • Keep the TOC at the top, but make it collapsible with little +/- buttons

I prefer the first option, but even just the second would make skimming to the very long list of sections a bit easier.

What do you think?


I definitly would appretiate that. This side by @grahamc has it too:

Something like this experiment I had laying around?

It might need some work to integrate with the website, and the fork (sorry can’t share right now) is extremely WIP and needs some cleanup. (Just now I rebased it on top of the current nixpkgs.)

If the community, and those in charge of the website, are interested in getting this up and running, then I’ll continue fixing this up, except acquiring feedback from the community, I think the interface is close to being just right.


This looks awesome! Reminds me just the tiniest bit of ReadTheDocs. How did you build this?


Samuel Dionne Riel via Nix community writes:

If the community, and those in charge of the website, are interested in getting this up and running, then I’ll continue fixing this up, except acquiring feedback from the community, I think the interface is close to being just right.

Just a piece of feedback: when clicking on a section title on the left
it scrolls at the right place but opens in the left-most menu the
section above it, which means one has to first click then scroll (even
just a bit) down in order to open the right scroll menu.

Apart from that, it looks awesome!

1 Like

Yes, I must say I do miss a side/good navigation in the current manual. BTW, whatever we choose, we should also consider how it looks in the text-mode browser that we offer in the installer.

The css of the nixos website is independent from what we use when building manuals for offline consumption.

I really like that the sidebar is aware of the current location I’m looking at, and updates itself accordingly.

I do agree with @Ekleog that the way the sections open is a bit surprising.

Given inspiration from all the existing documentation sites (e.g. the rust book, swift’s, read the doc, etc…) I went and looked at those, closed them, tried implementing what was good from all of them, and then worked a bit more until I was satisfied. So, it’s basically only styles + js over the existing DOM and existing tooling.

The DOM hasn’t been touched! Well, it is modified at load time using JavaScript, meaning that without JavaScript the manual acts like it did before, huge TOC in front, no fanciness. The experience with text-mode browsers should be 100% equivalent. Furthermore, if the JavaScript code is disabled by the end-user, they’re not left with an unusable manual.

I’m not sure what you meant here. This is changing the “offline consumption” manual, but it would be great if the dichotomy between the two manuals would disappear, and both would use 99% the same visuals and behaviour; I’m thinking the website would differ in having only an additional header and footer.

I’ll be looking at it, but I’m 99% confident it was because of the workarounds for the omnipresent header I had in the experiment (which I removed), which would cause surprises the other way around; as far as this experiment is concerned, it shouldn’t be an issue to be judged upon, it’ll behave as expected if we go through with it, I’ll make sure of it :).

I may also build a revision with the header for you all to look at, since I liked it, but I’m not sure it’s going to be a universal feeling. (Which is why I sent this version first.)


@samueldr any chances this could make it for 19.03? That would be really fantastic!

1 Like

We can also backport stylistic changes to 19.03 later on.


@samueldr has there been any progress in upstreaming your work on the manual?

Is there any way I can help?

I am not personally working on that at the moment, but I think someone is, even on something better. This is part of why I’m not working on that at the moment. If they’re interested in chiming in I’ll let them :).

I wrote some stylesheets to make the document looks better:

@-moz-document url-prefix("") {
    body > header {
        width: calc(100% - 320px);
        margin-left: 320px;
        padding-left: 20px;
        box-shadow: none;
        border-bottom: 1px solid #e9e9e9;
    main > section {
        max-width: calc(90% - 300px) !important;
        margin-left: 380px !important;
    div.docbook > div.toc {
        position: fixed;
        left: 0;
        top: 0;
        width: 320px;
        height: 100%;
        overflow-y: scroll;
        padding: 30px;

You can use Stylus or any other user stylesheet plugin to install it.



Still lack some handy features like, but it’s way better than the original.


Some suggestion from me:

  • move the TOC below the header
  • style the scrollbar

Header is not sticky, so if the TOC is below the header, when scrolling down, there will be a gap on top of the header.

The scrollbar style can be set easily by adding the following css in userstyle:

    div.docbook > div.toc::-webkit-scrollbar-track {
        -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.1);
        border-radius: 8px;
        background-color: #F5F5F5;

    div.docbook > div.toc::-webkit-scrollbar {
        width: 8px;
        background-color: #F5F5F5;

    div.docbook > div.toc::-webkit-scrollbar-thumb {
        border-radius: 8px;
        -webkit-box-shadow: inset 0 0 6px rgba(0,0,0,0.1);
        background-color: #a8a8a8;

which looks like this:

Hosted by Flying Circus.