2026-09-30 Documentation team meeting notes

Development Documentation
1

vision doc: nix.dev/maintainers/vision.md at master · NixOS/nix.dev · GitHub

Summary

Open format again, more people than usual this time. NixCon retrospective. Discuss a bag of migration topics. Nothing got a firm decision, but we are exploring the problem space and trying to map it to user intent. Since more people keep joining now we’ll try a structured agenda next time.

Content of the meeting

Agenda

@riotbib: can we make a structural agenda for future meetings?
@hsjobeki: sure, will prepare something for next time. Today stays open format.

NixCon retrospective

@trespaul: how was the NixCon workshop?
@paotsaq: people seem to think the docs are good, just hard to find.
@MattSturgeon: was mostly there to see what’s going on, also helped merge PRs during the workshop.
@hsjobeki: we didn’t have enough t-shirts; which means had >40 people in the room.

Markdown syntax

Looked at the Markdown syntax we currently use. Came out of the idea of adding a switch (tabs) between NixOS and Flakes usage examples in the docs.

Headings

  • Markdown linters complain if you have more than one h1.
  • MDN discourages multiple h1s too, and suggests styling h1 differently because of its special role.

Related, later on: @trespaul hit an h1 inside an example in the demo.
@MattSturgeon: there was a guide saying every example should have its own heading → probably that.
@hsjobeki: maybe put this on meta-attributes on the example blocks instead. We have too many headings everywhere.
@MattSturgeon: agreed.

{=include=} statements

Still need to get rid of the remaining ones. The old manuals break without migration (went through why).
@MattSturgeon: could add a flag just for the migration phase.
@hsjobeki: Need to think about it

bash doc-comments (i.e. for stdenv hooks)

@hsjobeki: we have no way to write doc-comments like we do for Nix functions.
@MattSturgeon: could we use the meta attribute?
@hsjobeki: that means we’d have to evaluate, but it could work.

Linter

@hsjobeki: we should have a Markdown linter that falls out of docs.nixos.org. Both for correctness and to catch bad stylistic syntax.

Anchors / stable URLs

@hsjobeki on mapping old anchors to the new pages. Versioning still unclear. Rough plan:

  • Drop redirects.json once we can.
  • Reduce the stability guarantee on anchors on docs.nixos.org.
  • Only URLs without anchors stay stable.
  • If something needs to be stable it has to have a resource ID as a stable URL (no #). Content at that location is free to change.

Splitting option docs

@MattSturgeon raised if/when/how to split up option documentation.
@hsjobeki: options.json gets rendered straight into docs.nixos.org, and the renderer decides how to split.
@MattSturgeon: had been trying to build something like that.
@hsjobeki: we want semantic grouping but don’t know how yet.
@trespaul: maybe split by declaration position?
@hsjobeki: tried that, no answer — coupling the split to any attribute just silently couples it to implementation details that don’t matter semantically.

Longer back-and-forth on this and no conclusion. Path-based splitting doesn’t match how users think. Take someone looking for “docker”: is it under services, under virtualisation, or is it a package you install like on other distros? Splitting by option path doesn’t answer that.

5 Likes
2

We also briefly touched on versioned content in the docs. The docs will include content from the Nix manual, Nixpkgs manual, and NixOS manual; each of which have multiple corresponding versions.

@trespaul suggested that sidebar sections could have their own “version” drop-down:

  • Nix - version: 2.34
  • Nixpkgs - version: unstable
  • NixOS - version: unstable
  • Guides - (no version)
  • Etc

@hsjobeki and @MattSturgeon discussed how the underlying versioned build & deployment could be structured.
Probably a build for the top-level site infrastructure and separate builds for each versioned documentation tree.
Would also need some form of composition for site structural JSON, used by the sidebar nav.

3 Likes
3

@hsjobeki You know I’m all behind your effort, but that part I strongly disagree on and ask you to reconsider. Yes, good search will reduce the importance of stable URLs. But you may be underestimating the length of a painful transition process on the way there. We had this in the past during the markdown migration 2020-2022, it sucked. Let’s not repeat it.

1 Like
4

I think the way the meeting notes frame it make it appear as we’re removing stability from the current manual; which is not the case at all. The redirects.json will probably need to stay around for a couple of releases even after the migration. What we’re looking at is how to reduce the maintenance burden of a 5000-line file that needs an entry for every single heading change.

On the new docs site we will be deliberate about giving these kind of stability guarantees. It will include the URI that is sure. For anchor id’s I’m thinking of a a two class model:

  • explicit identifiers that are stable.
  • auto-generated slugs that are best-effort.

Not every heading needs a stable ID, and we currently apply them far more widely than necessary. My first idea would be to partly derive that from the h-level (h1/h2) and use explicit heading attributes. The design of that system lays in the leanings from previous migrations and will be done very carefully. I’ll talk to you if we get to that part.

Also note what failure means in the new system. You’d still land on the same page.
mapAttrs#example is a small section withing a page and the entire page fits onto your screen without scrolling (much). If you mistype mapAttrs#ex-1 you’d still land on the same page and see the same content without even noticing any failure. In the old single-page manual, a broken anchor dropped you at the top of a huge document. In the new structure that is at most a small scroll. Best-effort becomes acceptable for most headings.

3 Likes
5

Right, we probably agree on the general direction: URLs should converge to be document-level, and documents should aim to be small enough for anchors not to matter.

The way you phrased it before made it sound as if you’d throw away the stable URLs (which almost all happen to be anchor-level at the moment), which I really think we should approximately never do.

6

My interpretation was that anchors on the current legacy docs will be mapped to pages on the new docs. Initially that can be auto-generated, until the current docs are phased out.

When the old docs URLs start redirecting to the new docs, we can use that anchor map to redirect the old stable anchors to the new stable pages.

On the new docs, anchors no longer need to be stable because we have stable pages URLs. But the redirects from the old docs anchors to the new docs pages still needs to remain stable.

1 Like
7

For the h1 lint behavior I think h1 should mainly for the title of the article itself perhaps. Something like this:

Article Title

Subject 1

  • About A
  • About B
  • About C

Subject 2

  • About A
  • About B
  • About C

Subject 2 deep dive