#175 ci: add an offline checker for internal Markdown links and anchors

[Anonymous]

Originally created by: fu351
Originally owned by: jasperdingg

Context

Doberman-Core has contributor, setup, security, and feature documentation spread across several Markdown files. A lightweight offline check would catch broken repository-local links and heading anchors before they merge.

Suggested starting points

• README.md, CONTRIBUTING.md, SECURITY.md, and docs/**/*.md
• scripts/
• tests/unit/
• .github/workflows/ci.yml

Acceptance criteria

• [ ] Add a small command-line checker for repository-local Markdown file links and #heading anchors.
• [ ] Scan the repository's maintained Markdown documentation deterministically.
• [ ] Ignore http://, https://, mailto:, and other external targets without making network requests.
• [ ] Ignore link-like text inside fenced code blocks.
• [ ] Resolve relative paths from the file containing the link.
• [ ] Reject links that resolve outside the repository root.
• [ ] Print useful file-and-line diagnostics and exit nonzero when a checked link is broken.
• [ ] Add the checker to CI.
• [ ] Add deterministic tests for valid links, missing files, valid anchors, missing anchors, external-link skipping, fenced-code skipping, and a path that escapes the repository.

Suggested validation

Run the focused test file, then run the checker against the repository's current documentation. The existing docs should pass without network access.

Out of scope

• Crawling or validating external websites.
• Rewriting documentation prose.
• Building a general-purpose Markdown parser.
• Checking non-Markdown assets unless needed to resolve a Markdown link.

Security and compatibility

The checker must remain offline and must canonicalize targets before reading them so a crafted ../ link cannot make CI inspect files outside the checkout. Diagnostics should contain paths and reasons, not file contents.

See CONTRIBUTING.md (github.com) before opening a pull request.

[Anonymous]

Originally posted by: jasperdingg

I'd like to take this one on, will send PR soon!

[Anonymous]

• assigned_to: jasperdingg

[Anonymous]

Originally posted by: fu351

Yours — assigned. Sorry for the slow reply.

Good pick to pair with [#194]: this one is self-contained and you can land it quickly, whereas [#194] is the meatier of the two. If you'd rather not run both at once, I'd do this one first.

A note on scope so the PR goes smoothly: the important word in the title is offline. The check must not make network requests — it only validates internal links and anchors (relative paths between repo Markdown files, and #anchor fragments resolving to a real heading in the target file). A checker that reaches out to the network would be non-deterministic in CI and would fail on a rate limit rather than a real problem, which is worse than no check.

Two things worth knowing before you start:

• There is real work for it to find. docs/CLI.md and docs/REASON_CODES.md both landed in the last few days and cross-reference each other and the README, so this isn't a check that trivially passes on day one.
• Whatever you use, make the failure output name the file, line, and the target that didn't resolve — the value of a link checker is entirely in how fast it tells you what to fix.

Same bar as [#221], which you already cleared: the check has to be able to actually fail. Worth adding a fixture with a deliberately broken link and anchor and confirming it goes red, rather than trusting a green run.

[Anonymous]

Originally posted by: fu351

Checking in on this one and [#194]: still planning to take them? No pressure and no deadline. If life happened, say the word and I will unassign so they go back in the pool, no hard feelings. If getting started is the sticking point, this one is the more self-contained of the two, and I am happy to answer questions right here. Discord too, if that is easier: https://discord.gg/Sfy5XGNqty

[Anonymous]

Originally posted by: jasperdingg

Sorry, I'll try to get them done within 1-3 days from now.

[Anonymous]

Originally posted by: fu351

No rush at all, and thanks for the heads-up. The check-in was only to make sure the ball wasn't stuck on my side. Ping me here or on Discord if anything in the checker or [#194] trips you up.

[Anonymous]

Originally posted by: fu351

Delivered by [#306] (merged). Thanks @jasperdingg!

[Anonymous]

Ticket changed by: fu351

• status: open --> closed