doc-link-audit

# Doc Link Audit ## Overview A dependency-free Python script that parses every `.md` file in a repo, resolves every `[text](target)` link, and reports what's actually broken: a missing file, a heading anchor that doesn't exist, or a page nothing else links to. It replicates GitHub's heading-slug algorithm exactly (including the double-hyphen case an em-dash produces) rather than a simplified approximation. **Core principle:** A link checker that reports false positives on doc examples and fenced code blocks isn't worth reading a second time — teams turn it off. Excluding code spans and fenced blocks from the scan is not an optional nicety here, it's what makes the tool's output trustworthy enough to act on without re-verifying by hand. ## Usage ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/check_links.py [root_dir] [--check-external] [--exclude PATTERN] ``` - Defaults to `.`. Exit code 0 = clean, 1 = findings, 2 = usage error. - `--exclude PATTERN` is a regex matched against each file path (e.g. `--exclude 'archive/|vendor/'`). - `--check-external` additionally HEAD-requests every `http(s)://` link found (off by default — slow, needs network, and a timeout or 403 from an otherwise-fine site is not the same as a broken link). ## What it reports | Section | Means | |---|---| | BROKEN LINKS | `[text](path)` where `path` doesn't resolve to a file, or `path#anchor` where the heading `anchor` doesn't exist in the target file | | ORPHAN PAGES | A `.md` file no other `.md` file...