docslinks

Documentation

Overview

docslinks walks every Markdown file in the repo and verifies that inline links of the form `[text](path)` or `[text](path#fragment)` resolve: the target file exists, and any `#fragment` matches either an explicit `<a id="fragment"></a>` element or a heading whose GitHub slug matches the fragment.

The audit found that earlier reference pages used `<!-- anchor: x -->` HTML comments as anchor targets — those are invisible to GitHub's Markdown renderer and silently fail to scroll. docsgen now emits real `<a id>` elements (see tools/docsgen/internal/mdwriter), and this checker guards against regression: any new `[label](#bad-slug)` link or any rename that breaks an existing one will fail the build.

Scope:

• Files: every Markdown root maintained in this repo — enumerated once, in discoverFiles — plus every **/*.md under docs/ and examples/. A root left off that list goes unchecked; that is how SECURITY.md came to carry three dead links.
• Inline Markdown links only (`[text](href)`). Reference-style and auto-links are out of scope — the docs don't use them.
• Local relative paths. URLs (http/https/mailto/etc) are skipped.
• File:line refs (e.g. `internal/foo.go:42`) are treated as plain file paths — fragment must look like an anchor slug, not a line number.

Exit codes: 0 = all green; 1 = broken links found; 2 = setup error.