2026-06-10 Documentation team meeting notes

Development Documentation
1

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

Summary

We discussed the path toward the documentation vision: standardizing on a common set of Markdown extensions, evaluating our rendering framework before committing further to Sphinx, clarifying which repositories own which rendering outputs, and a set of navigation quick wins that don’t require changing how pages are rendered. The main decision of the session was to merge tutorials and guides. Several open questions remain around resource consolidation, link checking, and versioning.

Notes

  • Among all the existing resources (nix.dev, manuals, wiki’s, etc.) which ones are to be kept, which ones to get rid of? Unresolved, needs a follow-up.

How can we get there?

Markdown standardization

versioning

  • Does nix.dev track nixos releases?
  • Does nix.dev track nix releases?
  • idea: guides stay constant, version switcher for nix/nixpkgs versions on reference material
  • Conclusion: nix.dev should own as little content as possible. Most content should live versioned along the sources; in nixpkgs and nix.

Rendering ownership & tooling

  • nixos-render-docs: currently renders HTML and man pages; the intended future is man pages only.
  • Idea: reuse nixos-render-docs for the docs migration by adding .md output with page splitting.
  • The nix / nixpkgs / nixos repos own their own man-page rendering.
  • nix.dev will own the HTML rendering from all .md sources.
  • nixos-search: uses Elm to render Elasticsearch results.
  • nix.dev will become docs.nixos.org after we are done.

Quick Wins

  • Improve navigation, without changing rendering:
    • Stylesheet for nix.dev
    • Common headers, aligned styles
    • Table of Contents collapsible
    • More content should be collapsed by default
  • We need more newbies to give us feedback :slight_smile:
  • Think about different users
    • Mac user: I want to use a cooler package manager
    • Linuxer: I want to install NixOS
    • Developer: I want to use nix for development
  • style mdBook in the nix repo

Action Items & Follow-ups

Item Owner
Find the smallest common denominator of Markdown extensions TBD
Framework evaluation before extending Sphinx further @hgl (to confirm)
Investigate link-checking integration (in-build vs. post-build) and how many pages need checking TBD
Resolve the versioning approach (does nix.dev track Nix / NixOS releases?) TBD
Collect the Markdown formats used across all repositories @hsjobeki, created: Collect markdown formats and documentation tools for all repositories · Issue #1238 · NixOS/nix.dev · GitHub
Collect the rendering tools used across all repositories @hsjobeki, created: Collect markdown formats and documentation tools for all repositories · Issue #1238 · NixOS/nix.dev · GitHub

Decisions

  • Merge tutorials and guides. Most people don’t care about or understand the diátaxis distinction between them. (Raised by @wamirez.)
13 Likes
Better navigation of nixos.org manuals
2

Thank you for the work that you folks are doing?

Just to confirm it sounds like the current content on nix.dev will become docs.nixos.org, if that is the case what is going to be the general knowledge for docs.nixos.org?

Will home-manager knowledge also be tracked now that it is part of NixOS now instead of a community add-on?

Great idea with the dead link checking! I should have done that when I was working on docs for a distro back in the day lol.

I like the thinking about different users, I’ve been trying to get folks on Ubuntu at work to use shell.nix files for projects (I have been doing myself when possible).

1 Like
3

Awesome work. Thank you!

Please start negotiating the aquisition of nix.org :folded_hands:

4

Another potential quick wins for users in future:

  • Windows User: I want to use a better/cooler package manager than Winget, Chocolatey & Scoop mess.
  • Software/Application/System etc.. administrator: I could use nix to deploy my app to a diverse platforms (aka via bundlers), make managing dev environments for developers easier and CI/Dev environments reproducible.

I thought I would mention the windows as this is what I am trying to work on as well, being one of the members apart of windows team.

5

This is a good initiative, though I’d recommend reaching out to corresponding teams for technical details. There are some very annoying technical issues when it comes to the nix manual.

  • nix.dev will own the HTML rendering from all .md sources.

Part of nix manual html and the —help markdown rending in nix is done in the nix language during the build process or at nix runtime. This is… certainly a choice, and it seems a bit incompatible with the above plan. What’s the preferred way to go about this? As it stands now, nix-manual html rendering is incredibly tightly coupled to the nix build process.

1 Like
6

Markdown rendering in nix is done in the nix language during the build process or at nix runtime

We take anything the nix repository exposes. Markdown files for what already is markdown.
We will provide a list of supported common-mark extensions. We’re not clear yet, whats inside it.
Ideally just the list of extension already in use. Otherwise me might leave gaps for the rendering markdown falls back to plain text if a feature is not supported.

The builtins might need a new pipeline that allows them to be consumed from an external repository. For https://noogle.dev i used nix __dump-language though that seems a bit internal, worked great for the past years.
We will reach out to the nix-team so we can negotiate about the formats possible. Ideally something that we agree is stable and intended for usage.

7

Will home-manager knowledge also be tracked now that it is part of NixOS now instead of a community add-on?

Afaik home-manager is in the process of becoming an official nixos resource. (I dont know the current stage)
Its not yet in scope for the first move of documentation. Once its official it should also be documented and should cohere to the same markdown interface. Then we can render it on docs.nixos.org

8

Fair enough! Thanks!

9

Huh, that’s news. As far as I recall the RFC for that was met with heavy opposition, notably the creation of hjem, since home-manager was considered of generally poor design.

Is this change sneaking by through backchannels?

10