USAGE

Quick Usage Guide

Problem

Your GitHub wiki has broken internal links. This validation system helps you find and fix them before committing.

Quick Start

1. Check for broken links

cd /path/to/wiki
python3 scripts/validate-wiki-links.py

This will show all broken links in your markdown files.

2. Understanding the errors

Common issue: Links include directory prefixes that shouldn't be there.

# ❌ Wrong (includes directory in link name)
[Quick Start](Quick-Start)
[API Overview](API-Overview)
[FlowSpec](FlowSpec-Overview)

# ✅ Correct (just the file name)
[Quick Start](Quick-Start)
[API Overview](API-Overview)
[FlowSpec](FlowSpec-Overview)

Why? GitHub wiki links use the file name only, not the directory path.

3. Fix the links

Option A: Auto-fix (recommended for bulk changes)

# Preview what will change
python3 scripts/fix-wiki-links.py --dry-run

# Apply the fixes
python3 scripts/fix-wiki-links.py

Option B: Manual fix Edit the markdown files based on the validator output.

4. Verify fixes

python3 scripts/validate-wiki-links.py

Should show: ✅ All wiki links are valid!

5. Commit

git add .
git commit -m "Fix wiki links"

The pre-commit hook will automatically validate before allowing the commit.

GitHub Wiki Link Rules

Rule 1: Use file name only (no directory path)

Your wiki has this structure:

wiki/
├── API/
│   ├── API-Commands.md
│   └── API-Overview.md
├── Getting-Started/
│   └── Quick-Start.md
└── Use-Cases/
    └── DDoS-Mitigation.md

Link to these files like this:

[API Commands](API-Commands)           # ✅ Just the filename
[Quick Start](Quick-Start)             # ✅ Just the filename
[DDoS Mitigation](DDoS-Mitigation)     # ✅ Just the filename

NOT like this:

[API Commands](API-Commands)                    # ❌ No paths
[Quick Start](Quick-Start)          # ❌ No directory prefix
[DDoS Mitigation](DDoS-Mitigation)        # ❌ No paths

Rule 2: No .md extension

[API Overview](API-Overview)       # ✅ No extension
[API Overview](API-Overview.md)    # ❌ Don't include .md

Rule 3: Anchors are lowercase with hyphens

# Header: "API Overview"
[Link](#api-overview)              # ✅ Lowercase, spaces → hyphens

# Header: "Getting Started (v5)"
[Link](#getting-started-v5)        # ✅ Parentheses removed

Pre-Commit Hook

The pre-commit hook runs automatically when you git commit.

If it blocks your commit:

1. Read the error message to see which links are broken
2. Fix those links
3. Try committing again

To bypass (not recommended):

git commit --no-verify

Troubleshooting

"target not found" errors

Problem: [Text](Page-Name) but Page-Name.md doesn't exist.

Solutions:

1. Check actual file name: find . -name "*Page*"
2. Remove directory prefixes from link
3. Check for typos

"anchor not found" warnings

Problem: [Text](Page#section) but Page.md doesn't have that header.

Solutions:

1. Check exact header text in target file
2. Remember GitHub converts to lowercase and replaces spaces
3. This is a WARNING, not an ERROR (won't block commits)

Pre-commit hook not working

Problem: Hook doesn't run on commit.

Solutions:

# Make hook executable
chmod +x .git/hooks/pre-commit

# Verify it exists
ls -la .git/hooks/pre-commit

# Test manually
.git/hooks/pre-commit

Examples

Before (broken links)

_Sidebar.md:
- [Quick Start](Quick-Start)     # ❌ Wrong
- [API Overview](API-Overview)               # ❌ Wrong
- [FlowSpec](FlowSpec-Overview)  # ❌ Wrong

After (fixed links)

_Sidebar.md:
- [Quick Start](Quick-Start)                     # ✅ Correct
- [API Overview](API-Overview)                   # ✅ Correct
- [FlowSpec](FlowSpec-Overview)                  # ✅ Correct

Need Help?

1. Run validator to see all errors: python3 scripts/validate-wiki-links.py
2. Check scripts/README.md for detailed documentation
3. File an issue on GitHub

---

Remember: GitHub wikis are flat - they don't use directory paths in links, only file names!