everyone-needs-a-copilot/link-validation

Link Validation

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

Purpose

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

Link Types to Validate

| Type | Pattern | Example | |------|---------|---------| | Relative file | [text](./path.md) | [Overview](./00-overview.md) | | Anchor | [text](#heading) | [Setup](#installation) | | File + anchor | [text](./file.md#section) | [Auth](./60-security.md#auth) | | Parent path | [text](../other/file.md) | [Index](../00-INDEX.md) | | Absolute (external) | https://... | Skip or warn |

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:

| Broken Link | Search Strategy | |-------------|-----------------| | ./old-name.md | Find files with similar names | | #old-heading | Find similar headings in file | | ../wrong/path.md | Search for filename in other directories |

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

| Issue | Cause | Fix | |-------|-------|-----| | File moved | Renamed with number prefix | Update link with new prefix | | Heading changed | Wording updated | Update anchor text | | Case mismatch | GitHub case-sensitive | Match exact case | | Missing extension | .md omitted | Add .md extension |