nixpkgs-manual: enable Markdown formatting with Prettier

[drupol]

This PR:

• Is a better and updated version of ci: add a check workflow on documentation #396914
• Add a new check nixpkgs-manual.tests.check-formatting (541861cefb2be3dbdc5702f57fdc470f0751bd16) using prettier
• Manually reformat some parts of the documentation to make it standard compliant with Markdown (3e924224a5235ff29013f5de667a5653cb4d9895, 77f7f186dd971b86850b02c0e6726ee25aba0575, cd5e67f8e908dd88344e69347ff680a6933520ed)
• Enable Python code blocks reformatting (c82b948efabee3e6c69fcc6b6380f303fd91efc1) thanks to markdown-code-runner
• Reformat the whole doc/ directory with prettier (822d5fc7bc48ce31005c50c081379bc425d78687)

⚠️ About definition lists

The most controversial point is the handling of definition lists, commonly written as:

Term
: Definition of the term

This format is part of what is referred to as “Markdown Extended” 1, but it is not part of the original or CommonMark specification. As a result, tools like prettier, which are widely adopted for Markdown formatting, do support basic definition lists, but they fail to preserve structure when those lists are nested.

Example: Nested definition list before and after Prettier formatting

Before:

Term 1
: Definition of term 1
  Term 2
  : Definition of term 2

After:

Term 1
: Definition of term 1
Term 2
: Definition of term 2

Try it in the Prettier playground

I agree that these nested definitions add meaningful structure. Unfortunately, there is currently no way to configure prettier to preserve this structure or disable this specific behavior.

The compromise solution

Rather than remove these lists or leave them unformatted (which would fail the automated check), I chose to preserve the meaning and pass prettier formatting by wrapping nested definitions in bullet points.

Rewritten as list items: preserves meaning, passes Prettier

Before:

- Term 1
  : Definition of term 1
  - Term 2
    : Definition of term 2

After (identical output):

- Term 1
  : Definition of term 1
  - Term 2
    : Definition of term 2

Try it in the Prettier playground

This way:

• We retain all content and structure, including nesting.
• Formatting is consistent and passes checks.
• No manual work is needed to maintain consistency going forward.

Commit 3ae1d6b28ab0833b17f1b06c4ed499a0e86da72a applies the above compromise and updates the documentation accordingly. As seen in the screenshots hereunder, the generated HTML is slightly different, I would argue that the readability and clarity have improved.

Simple example (before, after)

Example with nested definition list (before, after)

Let me know what you think! And if you disagree, perhaps it's worth considering a compromise so that we can benefit from an automated documentation checking system. The trade-off may well be worth it: would you rather rely on nested definition lists that aren't really standard and lose automation and checks, or accept a small compromise and gain all of that?

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[fricklerhandwerk]

This is wrong. It's supposed to be a term-definition in the paragraph that is part of the outer definition.

[drupol]

I don't think nested term-definition are officially supported in markdown. #investigating

[drupol]

I added a - (list item), would it be acceptable for you?

[drupol]

I guess I can mark this as resolved as I updated the current documentation before doing the formatting so that this issue won't happen again. Hope it's OK now.

[fricklerhandwerk]

Hm that seems to be a deficiency of any given markdown implementation (there's no such thing as "official" markdown). The semantics is valid DOM, so in a sense "not our problem". Making it a list item defies the original purpose.

It also seems inappropriate to iron over the work of @DanielSidhion and others who have put effort into adding more structure, just because some tool happens not to know that structure. This may appear like a minor thing, but I think it's sort of at the heart of what we're doing with Nixpkgs: we're building a knowledge base, and that's a big data structure. Removing information because some tools can't handle it seems wrong.

Is it possible to disable that particular behavior? Since the other changes look alright (haven't checked everything).

[drupol]

Right I hear you and fully agree. I'll write a post describing precisely what has been done so far to fix this issue at the end of the day, with screenshots and detailed explanation so we can decide what to do about this.

[fricklerhandwerk]

Thanks a lot @drupol!

[drupol]

I updated the OP with full details, explanation and screenshots. Let me know what you think.