Markdown relative link and anchor checker for docs and prompt repos
A dependency-free Python script and GitHub Actions workflow that find broken relative links and missing #heading anchors in Markdown files, without making any network calls.
Automation in Engineering by AISkillHub Library
What it does
Prompt libraries, agent instruction files and internal docs link to each other constantly: `AGENTS.md` points at `docs/testing.md#fixtures`, a skill references `examples/report.md`, a README links a section that was renamed last week. Renames and moves break these links silently. This check runs on every pull request that touches Markdown and fails when a relative link points at a file or heading that does not exist.
**What it checks**
- Inline links and images: `[text](path.md)`, `` - Same-file anchors: `[see setup](#setup)` - Cross-file anchors: `[fixtures](docs/testing.md#fixtures)` - Reference definitions: `[guide]: docs/guide.md` - Root-relative links (`/docs/x.md`) resolved from the repository root, the way GitHub renders them.
Anchors are matched against heading slugs generated the way GitHub does it (lowercase, punctuation removed, spaces to hyphens, `-1`, `-2` for repeated headings), plus any `id="..."` or `name="..."` attributes in inline HTML.
**What it will not do**
- It does not check external `http(s)` URLs. That keeps CI fast, deterministic and offline. Use a dedicated link checker on a schedule if you need that. - Links inside fenced code blocks and inline code are ignored on purpose. - Slug generation is an approximation. Headings that contain unusual Markdown or emoji can slug differently from GitHub; if you hit a false alarm, use `--no-anchors` or rename the heading.
**Example output**
``` AGENTS.md:14: missing file docs/testing-guide.md README.md:3: missing anchor #instalation in README.md checked 23 file(s), 2 broken link(s) ```
Exit codes: 0 no broken links, 1 broken links found, 2 a given path does not exist.
How to use it
1. Copy `scripts/check_md_links.py` and `.github/workflows/markdown-links.yml` into your repository. 2. Commit. The workflow runs on pull requests that change `.md` files and on pushes to `main`. 3. Run it locally from the repository root: ``` python3 scripts/check_md_links.py # all Markdown in the repo python3 scripts/check_md_links.py docs AGENTS.md # specific paths python3 scripts/check_md_links.py --no-anchors # files only python3 scripts/check_md_links.py --exclude "vendor/**" --exclude "CHANGELOG.md" ``` 4. Always run it from the repository root so root-relative links (`/docs/...`) resolve correctly.
Requires Python 3.8+ only. No packages, secrets or environment variables.
Files
Save each file at the path shown, relative to your project root.