ci/treefmt: add markdown-code-runner

[wolfgangwalther]

This was run as a test in doc/tests/check-nix-code-blocks.nix before, but its DX can be improved: By including it in treefmt we get better error reporting and auto-fixing, as well as running it on all markdown files (including READMEs etc.) for free.

This will need an update of the pin, which needs #427437.

Things done

• Fits CONTRIBUTING.md, pkgs/README.md, maintainers/README.md and other READMEs.

---

Add a 👍 reaction to pull requests you find important.

[drupol]

You can now enjoy a tag for markdown-core-runner: https://github.com/drupol/markdown-code-runner/releases/tag/0.2.0

And the PR that goes with it: #427516

[wolfgangwalther]

Converted to draft because of the DROP BEFORE MERGE commit in the middle. This pulls in markdown-code-runner from the current branch (not the pin), so that I could already do the formatting.

Formatting is done in 3 steps:

• First I fix all syntax errors in nix code blocks in the nixos manual.
• Then I run treefmt->mdcr->nixfmt.
• Then I fix some comments that were imho misplaced due to the auto formatting.

The first commit looks like I would do it, once the new markdown-code-runner is available in the pinned nixpkgs.

Ready for review, but not for merge.

[drupol]

To avoid too much work for you in case of conflict(s), I think the commit where you reformat everything should be the last of the list, so that you can easily drop it and recreate it in case of conflict(s).

[MattSturgeon]

Then I fix some comments that were imho misplaced due to the auto formatting.

Just to comment on this with my formatting team hat on:

Trailing comments are moved to their own line in some scenarios (iirc mostly just when they go over the line length), however nixfmt has no way to know if the comment should be moved to before or after the line it was previously on.

In the common example of a comment trailing a binding, it probably is more likely that the comment relates to the variable binding, but in other scenarios that may not be the case.

In most scenarios we'd anticipate the author noticing the auto-formatting not matching their desired layout and manually tweaking it, especially if they have configured treefmt-on-save in their editor.

Perhaps it's worth discussing this in an issue on the nixfmt repo though, so that we can go through some concrete examples and/or get insight from other formatting team members more familiar with the actual implementation. Maybe there is a strong argument for assuming the comment should usually go above instead of below?

[wolfgangwalther]

Maybe there is a strong argument for assuming the comment should usually go above instead of below?

I'd argue:

• A comment at the end of the line is always about that line.
• Comments on separate lines should usually go before the thing that they concern.

There are probably edge-cases where just moving the comment to the next line is the right thing... but my guess is that the majority of cases is better handled by moving them to the previous line instead.

[philiptaron]

(Note that the ✅ plus comments means that following the suggestion is extremely optional.)

[philiptaron]

🚀🌲🔢

Let's roll.

[MattSturgeon]

Strange CI failure here.

https://github.com/NixOS/nixpkgs/actions/runs/16754575116/job/47433571147?pr=427460

Unhandled error: Error: Could not find a push.yml workflow run for be2b8ea.

That commit is part of #430904, and CI never ran against that specific commit because it was pushed together with a later commit.

I'm not sure why this PR's eval is looking for a workflow run for an entirely unrelated commit, though?

[philiptaron]

We just were impacted by https://www.githubstatus.com/incidents/6swp0zf7lk8h @MattSturgeon

[MattSturgeon]

Strange failure mode for our get-merge-commit to return a random unrelated target commit... Oh well 😁

Do you have permission to restart the workflow run?

[philiptaron]

I do have permissions, but since the failures were so widespread, I expect a rebase would be best to reset it all.

[wolfgangwalther]

We can re-trigger CI without a rebase by close+open.

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/formatting-team-meeting-2025-08-05/67630/1