ci: format Markdown with mdformat instead of Prettier

[atdr]

What changed

Prettier is gone. mdformat formats Markdown instead, markdownlint-cli2 stays exactly as it was, and setup-node leaves ci.yml entirely.

Why

npx prettier@3.9.6 --check refetched Prettier from the npm registry on every run, and that fetch intermittently sat silent for exactly 301 seconds — npm's default fetch-timeout expiring, the retry then succeeding — in a job that takes twelve seconds when it is clean. atdr/contrail-gh#8 measured three stalls in six runs. The ten-minute timeout-minutes bound cannot catch it and never could: a run that recovers at 301s is under the bound by design.

Prettier also carried the last hand-edited version pin in CI, because it has no first-party action. mdformat is a Python tool, so the pin moves into pyproject.toml's dev extra where the pip Dependabot ecosystem already bumps everything else.

Refs atdr/contrail-gh#8. The matching change in the template is atdr/contrail-gh#16, and the two should land close together — docs/contrail-gh.md says these config files are copies, so a gap means the two repos disagree about what correct Markdown is. Land this one first; that PR's message says it matches this.

Why markdownlint-cli2 stays

Its action is JavaScript, so GitHub runs it on the runner's own Node with no toolchain to install and nothing fetched from a registry — it already sat before setup-node, which is the proof. Replacing it too would mean pymarkdownlnt, which has no per-file rule configuration, and two files here depend on a markdownlint-configure-file comment: README.md (MD013 at 100) and .github/pull_request_template.md (MD041 off, because it opens with a comment by design).

"No Node in CI" was never achievable anyway — actions/checkout and actions/setup-python are themselves JavaScript actions. "No Node toolchain to install, pin and fetch" is, and that is what this does.

Changes

Tooling (4aec3ff)

• ci.yml docs job: setup-node + npx prettier@3.9.6 out; setup-python at 3.13, pip install -e ".[dev]" and mdformat --check . in
• .prettierrc.json and .prettierignore deleted; .mdformat.toml added as their successor
• .pre-commit-config.yaml: rbubley/mirrors-prettier → hukkin/mdformat (the official Prettier mirror is archived, which is why we were on a fork)
• pyproject.toml: mdformat, mdformat-gfm and mdformat-frontmatter in the dev extra
• AGENTS.md, .markdownlint-cli2.yaml, docs/contrail-gh.md updated to match

Mechanical pass (8f800fa) — 5 files, 17 insertions, 6 deletions, no prose changed. Kept separate so the first commit stays reviewable, same shape as #23.

Two things worth a reviewer's attention

Python 3.13 for the formatter only. .mdformat.toml's exclude key hard-errors below 3.13, so ci.yml's docs job and the pre-commit hook both pin it, and the dev venv moves with them. requires-python is untouched and the matrix still tests 3.11, 3.12 and 3.13 — the interpreter that formats Markdown has nothing to do with the one a user installs contrails on. The alternative was writing the same three exclusions twice in two syntaxes, a shell filter and a pre-commit regex, which is the hazard .pre-commit-config.yaml already warns about, bought for nothing but the ability to format on an interpreter nobody here runs.

mdformat-frontmatter is a guard, not a fix. Without it mdformat does not recognise YAML frontmatter at all and rewrites the block into a horizontal rule and a heading. It did exactly that to a committed skill file in contrail-gh, caught by reading the diff. Nothing tracked here carries frontmatter today, but the failure is silent and the first .md that needs it would not announce itself.

.mdformat.toml also has to name venv/, which .prettierignore did not: Prettier and markdownlint-cli2 both read .gitignore, and mdformat does not. Without it a full-tree run walks into site-packages and finds hundreds of other projects' READMEs.

Checks

• ./venv/bin/ruff check . and ./venv/bin/ruff format . pass
• ./venv/bin/pytest -q passes
• Docs updated in this PR, if this changes a config option, an importer, or an emissions provider
• Tests added or updated, if this changes behaviour — n/a, no behaviour changed
• Skimmed gh issue list for open issues this change touches — none of the six are affected

Test plan

Run locally on Python 3.13, before and after the mechanical pass:

• markdownlint-cli2 v0.23.2 reports 0 issues in 13 files against mdformat's output. This is the one that matters — it proves the two tools agree rather than fight. Baseline on the Prettier-formatted tree was also 0
• mdformat --check . exits 0, and re-running changes nothing, proving idempotence
• pre-commit run --all-files passes every hook, with the mdformat hook env reporting Python 3.13.15
• pytest -q — 319 passed
• No table in the repo moved. mdformat-gfm pads cells byte-identically to Prettier
• The two release-please version pins in README.md are untouched by the formatting pass
• CLAUDE.md is still a symlink afterwards, not replaced by a regular file
• Negative tests, matching ci: check Markdown with markdownlint-cli2 and Prettier #23's: a deliberate 116-character line makes markdownlint exit 1, and an unpadded table row makes mdformat exit 1. Neither passes by failing to look
• CI green on this PR — every check passes. The markdown job ran in 18s, and all three pytest legs (3.11, 3.12, 3.13) still pass, confirming the dev-tooling Python bump did not touch the supported range

🤖 Generated with Claude Code

https://claude.ai/code/session_011mJ5NaA5DdPxqa1Mb4UJhT