If that's not possible, break the example down into multiple parts, explain them separately, and then show the combined result at the end.
  This should be a last resort, as that would amount to writing a [tutorial](https://diataxis.fr/tutorials/) on the given subject.

- Use British English.

  This is a somewhat arbitrary choice to force consistency, and accounts for the fact that a majority of Nix users and developers are from Europe.

### Links and anchors

Reference documentation must be readable in arbitrary order.
Readers cannot be expected to have any particular prerequisite knowledge about Nix.
While the table of contents can provide guidance and full-text search can help, they are most likely to find what they need by following sensible cross-references.

- Link to technical terms

  When mentioning Nix-specific concepts, commands, options, settings, etc., link to appropriate documentation.
  Also link to external tools or concepts, especially if their meaning may be ambiguous.
  You may also want to link to definitions of less common technical terms.

  Then readers won't have to actively search for definitions and are more likely to discover relevant information on their own.

  > **Note**
  >
  > `man` and `--help` pages don't display links.
  > Use appropriate link texts such that readers of terminal output can infer search terms.

- Do not break existing URLs between releases.

  There are countless links in the wild pointing to old versions of the manual.
  We want people to find up-to-date documentation when following popular advice.

  - When moving files, update [redirects on nixos.org](https://github.com/NixOS/nixos-homepage/blob/master/netlify.toml).

    This is especially important when moving information out of the Nix manual to other resources.

  - When changing anchors, update [client-side redirects](https://github.com/NixOS/nix/blob/master/doc/manual/redirects.js)

  The current setup is cumbersome, and help making better automation is appreciated.

The build checks for broken internal links with.
This happens late in the process, so [building the whole manual](#building-the-manual) is not suitable for iterating quickly.
[`mdbook-linkcheck`] does not implement checking [URI fragments] yet.


### Markdown conventions

The manual is written in markdown, and rendered with [mdBook](https://github.com/rust-lang/mdBook) for the web and with [lowdown](https://github.com/kristapsdz/lowdown) for `man` pages and `--help` output.

For supported markdown features, refer to:
- [mdBook documentation](https://rust-lang.github.io/mdBook/format/markdown.html)
- [lowdown documentation](https://kristaps.bsd.lv/lowdown/)