#298 ci: offline Markdown link and heading-anchor checker

[Anonymous]

Originally created by: AshSgDe29071999

Summary

• Add scripts/check_markdown_links.py: offline checker for repository-local Markdown file links and #heading / HTML name/id anchors.
• Deterministic scan of maintained docs (README.md, CONTRIBUTING.md, SECURITY.md, other root *.md, docs/**/*.md).
• Skip http(s):, mailto:, and other external schemes (no network).
• Ignore link-like text inside fenced code blocks.
• Resolve relative targets from the linking file; reject paths that escape the repository root.
• Print file:line: reason: target diagnostics and exit nonzero on failure.
• Wire the checker into .github/workflows/ci.yml.
• Unit tests cover valid links, missing files, valid/missing anchors, external skip, fenced-code skip, and repo-escape.
• Fix one broken TOC anchor in docs/SETUP.md so current docs pass the checker.

Test plan

• [x] pytest tests/unit/test_check_markdown_links.py
• [x] python scripts/check_markdown_links.py → ok on current docs
• [x] ruff check / ruff format on the new files

Fixes [#175]

[Anonymous]

Originally posted by: fu351

First, thank you, and I'm sorry this one lands as a duplicate. You and @jasperdingg built the same checker in parallel, and [#175] was already assigned to them, so the plan is to land [#306] and close this one in its favor. That's an assignment call, not a quality one, and I want to be clear about that.

There's one thing your version does better that I don't want to lose: you check existence for any local target (images, assets, directories), not just .md files. [#306] deliberately skips those, so broken asset links slip past it — a real gap in the one we're landing. If you'd open a small follow-up to add asset-existence checking on top of [#306] once it's in, I'd take it happily and credit it to you.

A couple of honest notes on this PR, since they're what tipped it: the curated DEFAULT_GLOBS misses 8 of the repo's 23 Markdown files today (a full-tree walk avoids that), reference-style [text][ref] links aren't parsed, and the diagnostics print backslash paths on the Windows CI leg. None of that takes away from the work — your anchor and fence handling were solid.

Given how much you've shipped this week, a natural next piece: #192 — a shared JSON-output contract across the CLI's JSON commands. It builds straight on the status --json work in your [#315]. Want it? It's yours.

Thanks again, and genuinely glad you're building here.

[Anonymous]

Ticket changed by: fu351

• status: open --> closed