search

NixOS / nix.dev

Official documentation for getting things done with Nix.
https://nix.dev
Creative Commons Attribution Share Alike 4.0 International
2.47k stars 249 forks source link

Inconsistent styling and lack of cross project navigation in Nix documentation #837

Open lf- opened 9 months ago

lf- commented 9 months ago

Observations

https://nix.dev/reference/nix-manual and the nixpkgs and NixOS manuals and nix.dev don't have any navigation links between them or consistent styling.

related discussion https://logs.nixos.dev/room/!avYyleMexqjFHoqrME:nixos.org/?anchor=$1a-p0jIFGfppHqFadSnQIpoX40mUALH9qt7griX9qWk&offset=-10

Problem

The docs appear disjoint and not obviously under the umbrella of a unified team, and not obviously official.

Approaches

We could rectify this first with the baby step of a global navigation bar on nix.dev and nix docs without restyling the sites and go from there.

Willing to help?

Maybe, unsure exactly how to approach since the stuff is all separate unrelated code bases at present.

Priorities

Add :+1: to issues you find important.

fricklerhandwerk commented 9 months ago

I propose the following sequence of steps:

  1. Pull out the Nixpkgs and NixOS manuals out of nixos.org into nix.dev at all

    I had started this, but I have lots of higher priorities, so it won't happen in the next weeks. I can share my crufty local branch if anyone is interested in picking it up.

  2. Add consistent-looking style sheets to each of the manuals.

    I was playing with the idea of doing it upstream, but this may need discussion.

    Advantages:

    • Building locally will give you the same result as you'd observe hosted online. Currently this is only the case for the Nix manual, for the reason that there is no styling applied whatsoever.
    • Allows working on style issues independently, since the build setups differ for the current three officially documented projects. There may be more in the future, and keeping those custom information downstream will likely add friction.

    Disadvantages:

    • Duplicates some styling code across projects, with a risk of going out of sync
    • Requires backporting the style additions to all actively supported versions.

Side note: I'm really not a fan of mdBook, it's not very mature compared to e.g. Sphinx. And while that sort of works, I'm not a big fan of Sphinx either. All these static site systems are too simple-minded for our use cases and need hacks and customisation. And highly bespoke usage is really problematic because it tends to be brittle and undocumented, but we need our docs infrastructure to be both powerful and low-tech while meshing with the Git/GitHub workflow.

By low-tech I mean: