We discussed how to structure docs.nixos.org, how to handle page splitting and where documentation content should live. The main decisions of the session were that content should be co-located with its source in the nix/nixpkgs repositories rather than nix.dev, and that nix.dev should become a pure static site renderer consuming markdown output from nixos-render-docs. The biggest open question — how many pages page-splitting would produce across the manuals — was followed up after the meeting by @hsjobeki with a dedicated evaluation.
We reviewed the existing manuals and decided on a top-level split into three sections: Nix, NixOS, and nixpkgs.
Pages will be split down to an H3 heading structure. This will likely be configurable, as the right granularity varies between manuals and will need some adjustment.
Page splitting and content volume
The biggest open question after the session: how much content will we have if we do page splitting on the Nix / NixOS / nixpkgs manuals?
As a follow-up, @hsjobeki did a small evaluation to estimate page counts.
Documentation content should live in the nixpkgs / nix repositories, not in nix.dev.
Content in nix.dev gets out of sync with the tools it documents and is not versioned alongside them.
With the transition to docs.nixos.org, the remaining content on nix.dev will be reviewed and what is still valuable will be moved to the nixpkgs or nix repository.
docs.nixos.org should become a static site renderer only:
It takes the markdown output produced by nixos-render-docs (nrd) and renders it into html.
The rendered site contains all the content of the current manuals, split into logical pages.
Action Items & Follow-ups
Item
Owner
Page count estimate for nrd page splitting across Nix / NixOS / nixpkgs manuals
Review remaining nix.dev content and identify what to migrate to nixpkgs / nix
TBD
Determine page-splitting granularity for nrd (section / chapter / etc.) and whether config file is needed
TBD
Framework evaluation: can Sphinx meet all requirements (content volume, search, SEO, accessibility, mobile, extensibility)?
TBD
Decisions
Content lives in nixpkgs / nix, not in nix.dev. Documentation that is not co-located with its source gets out of sync and loses versioning. nix.dev content that is still valuable will be migrated to the appropriate upstream repository.
docs.nixos.org becomes a pure static site renderer. It will consume markdown output from nixos-render-docs and produce the docs.nixos.org website, with manual content split into logical pages. If the amount of pages to render is too large we’ll probably transition to server side redering some of the pages.
Great stuff. Small nit on the tech: I agree the docs site should simply aggregate the material from different components and ideally display it in a somewhat consistent style. But it shouldn’t render it – build from source, sure, but not own a part the pipeline. Otherwise you’ll again have split authority. It would be enough to fix up the CSS and maybe do some light patching, but ideally upstream eventually would use a common library, or something like that.
I think we’re largely aligned on the principle, authority for us is mostly a governance concern, not only a technical one. The most important question for us was: “how can we provide the best user experience and discoverability of content?”
producing HTML pages with navigation, search, and consistent styling. Is a presentation concern best solved by one central renderer. Consider the alternative: having each upstream repo produce its own final HTML. That would mean coordinating CSS, search indexing, cross-manual linking, and layout and components across multiple independent builds, which is the fragmentation we’re trying to avoid. Not to mention it seems complex.
Our envisioned road: each repository emits markdown in an agreed-upon format.
structure and content is owned by each repository. nix.dev (future docs.nixos.org) will then render the whole content and verify all links are correctly pointing to each other. One homogeneous static site, many pages.
Of course this raises new questions, like if somebody moves a document they’d need to open an accompanying PR in another repo, where pointers to the file existed, now are void.
In our vision cross-repo link validation in CI and clear migration procedures will handle that.
Here is the part i don’t agree with:
It would be enough to fix up the CSS
Short term for quick wins, this is what we are doing already.
Long term, patching stylesheets doesn’t scale. CSS breakages are silent and hurt users more than it sounds. Content may become inaccessible, unreadable or the site navigation may stop working. As soon as docs.nixos.org becomes a real portal styling gets more complex and nested.
The renderer needs to own the complete presentation layer coherently.
By authority I don’t mean it in terms of governance, but where the source lives and what’s need to manipulate it.
We had this with the Nix manual back when it was rendered on nixos.org, and the result was that you’d commit something to the Nix repo which didn’t have those checks, and get build failures downstream, so then you have to go back and commit again, etc.
Thus what I mean by patching CSS I mean absolutely superficial things at best that wouldn’t make sense to handle upstream. Because as you say, you can’t do things from downstream and expect them to generally work.
I already mentioned it in the past, but I think that’s a lot harder than it sounds. There’s so many traps in that, for instance even having upstream maintainers agree to do the change and someone doing the work to port and fix the errors. Just imagine having to tell the Nix or Home Manager teams “please merge this series of PRs that look like absolute noise, because we’d like to display your work somewhere else in a way we really like”. Changing the format (which you will at some point) also means you may have breakpoints beyond which you can’t meaningfully render old versions (which you probably want to do though, since Nix advances independently of which version Nixpkgs includes).
Which is why I suggest taking a much more careful approach: narrow down the protocol incrementally (e.g. “this is the HTML format for admonitions or TOCs, so we can render them in the same style everywhere”), slowly introduce checks to upstream that will prevent violations (such as e.g. GitHub actions that will build downstream against unmerged PRs and raise issues), and support maintainers with doing the right thing in a way that makes sense for them and doesn’t introduce extra work or, worst, cyclic dependencies. Maybe from that perspective, my suggestion of initially taking the builds exactly as they are and, where needed, lightly patching them up, and otherwise introduce e.g. central stylesheets to upstream repos, sounds more sensible than at first glance?
I think we may be approaching this from different layers. Coordinating HTML, CSS, and post-rendering concerns across multiple independent repos is a much harder contract to enforce than coordinating a decentralized collection of CommonMark. Markdown easy to lint and validate.
“This HTML will render correctly in the portal” does not.
Even if you get away with that, my prediction is that it would look and feel like a patchwork quilt.
We should discuss this, but i’d like to note, that we plan to validate these assumptions through practical spikes.
So we’ll add any concern raised and do a spike for that. versioning is also on that list, and i know from experience its indeed underestimated, but can be done.
my prediction is, if we find a practical way with markdown we will end-up with a much nicer user-experience. The problems you raised can be solved at both levels and need verification.
