Better navigation of nixos.org manuals


#1

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?


#2

I definitly would appretiate that. This side by @grahamc has it too: https://docbook.rocks/


#3

Something like this experiment I had laying around?

It might need some work to integrate with the nixos.org 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.


#4

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

roni


#5

Samuel Dionne Riel via Nix community nixos1@discoursemail.com 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!


#6

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.


#7

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


#8

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.


#9

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 nixos.org 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.)