I was navigating the Nixpkgs manuals lately, and a couple of tweaks came to mind that would make navigation a lot easier:
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: https://docbook.rocks/
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.
This looks awesome! Reminds me just the tiniest bit of ReadTheDocs. How did you build this?
roni
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!
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 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.)
@samueldr any chances this could make it for 19.03? That would be really fantastic!
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("https://nixos.org/manual/nixos") {
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.
Before:
After:
Still lack some handy features like readthedocs.io, but it’s way better than the original.
Some suggestion from me:
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:
Is there any update on this? And wouldn’t it better to use one of the many documentation frameworks that already have done all the work? Why not use the same thing that nix.dev is using?
Ideally something that uses (extended) markdown, since this is the de facto standard documentation format in IT.
I think that more than adding navigation (which is nice), it would be best to split it in separate chapters.
The manual keeps growing and growing. Having nice navigation and different chapters would help a lot. For example, if you search for makeWrapperArgs because you’re interested in python stuff, you’ll have to jump a lot across other languages supported that also have the same feature. Another example is searching for “k3s” in the changelog. You’ll end up having a lot of results for older releases that don’t care for a single-version jump.
Thanks for keeping those nice manuals, anyways!
I’m pretty new to Nix, so I’ve been consulting the documentation a lot. One thing I’ve noticed is that when I google something it almost never refers me to the NixOS manuals. It prefers the guides, NixOS Discourse, and other sources like that.
I think I know the reason too. Google and other search engines usually won’t split a page up and index it under a bunch of anchor links. Not having the Nixpkgs and NixOS manuals broken up (at least by chapter) is harmful in this way.
(It’s slightly edited from a post I made on reddit. This is a good place for it to be as well.)
@johnkyle this is a well-known problem. @GetPsyched (with a bit of my guidance) is currently working on solving that by building infrastructure that allows splitting the manuals into separate pages without breaking all the URLs. This will take some time to fully come to fruition, but we’re planning to show first results in the next weeks.
