dykyi-roman Documentation Link Validation
Analyze documentation files for broken links, missing targets, and navigation issues.
Detection Patterns
1. Broken Relative Links
<!-- BROKEN: Target file doesn't exist -->
See [installation guide](docs/install.md)
<!-- File docs/install.md not found -->
<!-- BROKEN: Wrong path depth -->
See [API docs](../docs/api.md)
<!-- Should be ./docs/api.md -->
<!-- BROKEN: Case mismatch -->
See [README](readme.md)
<!-- Actual file is README.md -->
2. Broken Anchor Links
<!-- BROKEN: Anchor target doesn't exist in file -->
See [Configuration](#configuration)
<!-- No ## Configuration heading found -->
<!-- BROKEN: Anchor in another file -->
See [API Authentication](docs/api.md#auth)
<!-- docs/api.md exists but has no ## Auth heading -->
<!-- BROKEN: Wrong anchor format -->
See [Setup](#set-up)
<!-- Heading is "## Set Up" → anchor should be #set-up -->
3. Malformed URLs
<!-- MALFORMED: Missing protocol -->
See [docs](www.example.com/docs)
<!-- MALFORMED: Space in URL -->
See [guide](docs/getting started.md)
<!-- MALFORMED: Unencoded special characters -->
See [API](docs/api?version=2&format=json)
4. Orphaned Documentation
<!-- File exists but no other doc links to it -->
docs/deprecated-api.md <!-- Not linked from any other .md file -->
docs/internal-notes.md <!-- Not in any navigation/TOC -->
Grep Patterns
# All markdown links (relative)
Grep: "\]\([^http][^:][^/][^)]+\)" --glob "**/*.md"
# All markdown links (absolute)
Grep: "\]\(https?://[^)]+\)" --glob "**/*.md"
# Anchor links
Grep: "\]\(#[^)]+\)" --glob "**/*.md"
# Cross-file anchor links
Grep: "\]\([^)]+\.md#[^)]+\)" --glob "**/*.md"
# Image references
Grep: "!\[[^\]]*\]\([^)]+\)" --glob "**/*.md"
# HTML links in markdown
Grep: "href=\"[^\"]+\"" --glob "**/*.md"
Validation Process
Step 1: Extract All Links
# Find all relative links
Grep: "\]\(([^http][^)]+)\)" --glob "**/*.md"
# Find all anchor links
Grep: "\]\((#[^)]+)\)" --glob "**/*.md"
Step 2: Verify Targets Exist
For each relative link [text](path):
- Resolve path relative to the source file's directory
- Check if target file exists using
Glob - If link has
#anchor, verify heading exists in target
Step 3: Check Anchor Targets
For each anchor link [text](#heading):
- Convert heading to anchor: lowercase, replace spaces with
-, remove special chars - Search for matching heading in the file
- Report if no match found
Step 4: Find Orphaned Docs
# List all .md files
Glob: **/*.md
# For each file, check if it's referenced by any other .md
Grep: "filename.md" --glob "**/*.md"
# If referenced by 0 files and not README/CHANGELOG → orphaned
Severity Classification
| Pattern | Severity |
|---|---|
| Broken link to critical doc (README, install) | 🔴 Critical |
| Broken relative link | 🟠 Major |
| Broken anchor link | 🟡 Minor |
| Malformed URL | 🟡 Minor |
| Orphaned documentation | 🟡 Minor |
Output Format
### Link Validation: [Description]
**Severity:** 🔴/🟠/🟡
**Source:** `file.md:line`
**Link:** `[text](target)`
**Type:** Relative/Anchor/External/Image
**Issue:**
[Description — target not found, anchor missing, etc.]
**Fix:**
- Correct path: `[text](correct/path.md)`
- Or remove dead link
Summary Report Format
## Link Validation Summary
| Metric | Count |
|--------|-------|
| Total links checked | X |
| Valid links | X |
| Broken relative links | X |
| Broken anchors | X |
| Malformed URLs | X |
| Orphaned files | X |
### Broken Links
| Source | Link | Issue |
|--------|------|-------|
| `README.md:45` | `[guide](docs/guide.md)` | File not found |
| `docs/api.md:12` | `[auth](#authentication)` | Anchor not found |