MDX format check does not detect formatting drift (lint-only, no diff)

[Aryex]

Problem

pnpm format:check:mdx does not fail on MDX/Markdown files that are not in formatted shape. It only reports remark lint warnings, so any change that pnpm format:mdx would apply — but that isn't backed by a lint rule — silently passes CI.

This is not just theoretical. On PR #244 (docs: add resilience best practices guide), CI's Static Checks job passed, but src/content/docs/how-to/connections/resilience-best-practices.mdx still needed formatting changes when I ran the formatter locally afterwards:

• - → * list markers
• <TabItem> children re-indented
• Code fences under <TabItem> re-indented

The follow-up commit 6a60afc format: applied formatting made 163 line changes to that single file — none of which the format check flagged.

Root cause

scripts/check-format.sh runs:

npx remark --no-stdout "src/content/docs/**/*.{md,mdx}"

remark --no-stdout only emits lint plugin warnings. It never diffs the input against what remark --output (the actual formatter used by pnpm format:mdx) would write. Style-only normalizations (list markers, indent, code-fence indent inside custom directives, etc.) are formatting rewrites, not lint rules, so no warning is ever emitted for them.

Unlike Prettier, remark has no built-in --check mode, so the current script's premise — "no lint warnings ≡ formatted" — conflates two independent things.

Reproduction

# Restore the pre-format version of the file that shipped in PR #244
git show 6628dbb:src/content/docs/how-to/connections/resilience-best-practices.mdx \
  > src/content/docs/how-to/connections/resilience-best-practices.mdx

pnpm format:check:mdx
# ✅ PASS: No unexpected warnings found   ← but the file is not formatted

Proposed fix

Rewrite scripts/check-format.sh to mirror the real format:mdx pipeline and diff:

1. Copy src/content/docs to a temp directory.
2. Run remark ... --output against the copy using the repo's .remarkrc.json.
3. Run scripts/fix-remark-escapes.sh against the copy (so the check matches what the formatter actually produces).
4. diff -ruN the copy against the source. Any diff fails the check with the list of drifting files.
5. Still filter the known-false-positive no-undefined-references warnings from Starlight's [!NOTE] shorthand, so real remark warnings continue to fail the check.

Runtime cost on the current tree (~109 files): ~1.2s vs. ~0.6s today. Negligible for CI.

Bonus catch

While validating the proposed fix locally, it also flagged pre-existing formatting drift in src/content/docs/how-to/security/tls.mdx (Go code-fence indent inside a raw string literal in the mTLS example) that the current check has been silently accepting.