Link Validation

Link Validation

Validate markdown links and cross-references to ensure documentation integrity.

Purpose

Broken links in knowledge-copilot waste Claude's time and tokens. This skill finds and fixes broken internal links, missing anchors, and incorrect cross-references.

Link Types to Validate

Procedure

1. Find All Markdown Files

find . -name "*.md" -type f -not -path "./_archive/*"

2. Extract Links from Each File

Use grep to find markdown links:

grep -oE '\[([^\]]+)\]\(([^\)]+)\)' file.md

3. Categorize Links

For each link:

• External (starts with http): Skip or optionally validate
• Anchor only (#heading): Validate heading exists in same file
• Relative file: Resolve path and check file exists
• File + anchor: Check both file and heading exist

4. Validate Internal Links

For relative paths:

# From the file's directory, check if target exists
target_file="resolved/path/to/target.md"
if [ -f "$target_file" ]; then
  echo "OK: $target_file"
else
  echo "BROKEN: $target_file"
fi

5. Validate Anchors

Anchors should match headings (lowercase, hyphens for spaces):

# Extract headings from target file
grep -E '^#{1,6} ' target.md | sed 's/^#* //' | tr '[:upper:]' '[:lower:]' | sed 's/ /-/g'

6. Attempt Auto-Fix

For broken links, search for likely correct targets:

Output Format

## Link Validation Report

### Summary
- Files scanned: N
- Total links: N
- Valid: N
- Broken: N
- Warnings: N

### Broken Links

| File | Line | Link | Issue | Suggested Fix |
|------|------|------|-------|---------------|
| docs/setup.md | 45 | `./old-guide.md` | File not found | `./10-guide.md` |
| docs/api.md | 23 | `#authenication` | Anchor not found | `#authentication` |

### Warnings

| File | Link | Warning |
|------|------|---------|
| docs/intro.md | `https://old.example.com` | External link (not validated) |

### Fixes Applied
- docs/setup.md:45 - Changed `./old-guide.md` to `./10-guide.md`

Cross-Reference Patterns

Link Registry Pattern

If 00-links.md exists in a directory, validate all links defined there:

## Internal Links
- ecosystem: ../00-ecosystem-overview.md
- glossary: ../../03-ai-enabling/03-operations/12-shared-glossary.md

Source of Truth Pattern

Frontmatter may reference external docs:

source_of_truth: ../../insights-copilot/docs/04-architecture/system-design.md

Validate these paths exist (may be outside current repo).

Common Issues