validate-wiki-links

description

Validates all [[wiki links]] and

Validate Links

Command Purpose: Ensure knowledge base integrity by:

1. Validating all [[wiki links]] and #[[tag links]] in the Logseq repository
2. Identifying broken references (links to non-existent pages)
3. Reporting validation results with clear actionable insights
4. Optionally creating stub pages for missing links

When Invoked: This command executes directly using the logseq-validate-links CLI tool (from stapler_logseq_tools package).

---

Core Methodology

Phase 1: Link Validation

Objective: Scan all Logseq files and validate internal link references.

Actions:

1. Scan Logseq directories:

   • Pages: ~/Documents/personal-wiki/logseq/pages/*.md
   • Journals: ~/Documents/personal-wiki/logseq/journals/*.md
   • Extract all [[Page Name]] and #[[Tag Name]] references

2. Validate each link:

   • Check if target page exists in pages directory
   • Handle filename variations (spaces, underscores, case)
   • Track which files contain each broken link

3. Execute validation tool:

   cd ~/Documents/personal-wiki
   logseq-validate-links validate
   

Success Criteria:

• All markdown files scanned successfully
• All links extracted and checked
• Broken links identified and categorized
• Validation summary generated

Validation Output Format:

🔗 Broken Links Found
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Missing Page       ┃ Referenced In                ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ New Concept        │ 2025_10_13.md               │
│ Technical Topic    │ Some Page.md, Another.md    │
└────────────────────┴──────────────────────────────┘

📊 Link Validation Summary
┏━━━━━━━━━━━━━━━━┳━━━━━━━┓
┃ Metric         ┃ Count ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━┩
│ Total Pages    │   156 │
│ Files Validated│    89 │
│ Valid Links    │   423 │
│ Broken Links   │     2 │
│ Tag Links      │    78 │
└────────────────┴───────┘

---

Phase 2: Results Analysis and Reporting

Objective: Interpret validation results and provide actionable recommendations.

Actions:

1. Categorize broken links:

   • High priority: Referenced in multiple files (core concepts)
   • Medium priority: Referenced in journal entries (recent work)
   • Low priority: Single reference in older content
   • Potential typos: Similar to existing pages (Levenshtein distance < 3)

2. Analyze patterns:

   • Identify common missing concepts (themes across broken links)
   • Detect potential typos or case mismatches
   • Find orphaned references (links to pages that never existed)

3. Generate recommendations:

   ## Link Validation Report
   
   **Status**: [✓ All links valid] OR [⚠ Broken links found]
   
   **Broken Links Summary**:
   - High priority (multiple references): [count]
   - Medium priority (journals): [count]
   - Low priority (single reference): [count]
   - Potential typos: [count]
   
   **Recommendations**:
   1. Create pages for high-priority concepts: [[Concept 1]], [[Concept 2]]
   2. Fix potential typos:
      - [[Kuberntes]] → [[Kubernetes]] (referenced in file.md)
   3. Review orphaned references: [[Old Topic]] (may no longer be relevant)
   

Success Criteria:

• All broken links categorized by priority
• Patterns and typos identified
• Clear recommendations provided
• User can immediately take action

---

Phase 3: Stub Page Creation (Optional)

Objective: Create placeholder pages for missing links to restore reference integrity.

When to Use:

• Mode 1 (auto_fix=true): Create stubs automatically for all broken links
• Mode 2 (auto_fix=false): Report broken links, await user confirmation before creating stubs
• Mode 3 (selective): Create stubs only for high-priority links (multiple references)

Actions:

1. Determine stub creation strategy:

   • If ${2} (auto_fix) is "true" or "all": Create stubs for all broken links
   • If ${2} is "selective": Create stubs only for high-priority (multi-referenced)
   • If ${2} is unset or "false": Report only, don't create stubs

2. Execute stub creation:

   Automatic mode:

   logseq-validate-links validate --create-missing
   

   Manual mode (create specific stubs): For each missing page:

   • Create file at ~/Documents/personal-wiki/logseq/pages/[Page Name].md
   • Use structured stub template (see below)
   • Preserve exact page name from link

3. Stub template structure:

   - **Core Definition**: [Page Name]
   
   ## Background/Context
   - TODO: Add context and background information
   
   ## Key Characteristics/Principles
   - TODO: Add key characteristics
   
   ## Related Concepts
   - TODO: Add related concept links
   
   ## Significance
   - TODO: Add significance and importance
   
   **Related Topics**: #[[TODO]]
   

4. Verify stub creation:

   • Confirm files created successfully
   • Re-run validation to verify broken links resolved
   • Report number of stubs created

Success Criteria:

• Stubs created for all intended pages
• Structured template used consistently
• Links now resolve successfully
• Re-validation confirms resolution

---

Phase 4: Verification and Next Steps

Objective: Confirm validation results and guide user on follow-up actions.

Actions:

1. Re-validate if stubs created:

   logseq-validate-links validate
   

   • Confirm broken link count reduced to zero (or only intentional omissions)
   • Report any remaining issues

2. Provide next steps:

   If stubs created:

   ✓ Created [count] stub pages for broken links.
   
   **Next Steps**:
   1. Review stub pages and add comprehensive content:
      - [[Page 1]] - Referenced in [file1.md, file2.md]
      - [[Page 2]] - Referenced in [file3.md]
   
   2. Consider using /knowledge/process-journal-zettels to generate
      research-backed content for these pages.
   
   3. Run validation again after content updates to ensure quality.
   

   If only reporting:

   ⚠ Found [count] broken links.
   
   **Next Steps**:
   1. Decide whether to create stub pages:
      - Run: `/knowledge/validate-links all true` to auto-create all stubs
      - Run: `/knowledge/validate-links selective true` for high-priority only
   
   2. Fix potential typos manually:
      - [[Typo]] → [[Correct Name]] in [file.md]
   
   3. Remove obsolete references if concepts are no longer relevant.
   

3. Generate completion summary:

   ## Validation Complete
   
   **Initial State**:
   - Broken links: [count]
   - Files affected: [count]
   
   **Actions Taken**:
   - Stubs created: [count] (or "None - report only")
   - Typos identified: [count]
   
   **Final State**:
   - Broken links remaining: [count]
   - Validation status: [✓ Pass / ⚠ Review needed]
   
   **Files Created**:
   - ~/Documents/personal-wiki/logseq/pages/[Page1].md
   - ~/Documents/personal-wiki/logseq/pages/[Page2].md
   

Success Criteria:

• Final validation status confirmed
• Clear next steps provided
• User understands what was done and what remains
• All created files documented

---

Advanced Features

Statistics Mode

Purpose: Get high-level wiki health metrics without detailed validation.

Usage:

logseq-validate-links stats

Output:

📊 Wiki Statistics

Overall Health:
- Total pages: 156
- Total journals: 245
- Unique links: 423
- Unique tags: 78
- Broken links: 2 (0.5%)

Most Connected Pages (outbound links):
1. [[Platform Engineering]] - 45 links
2. [[Database Design]] - 32 links
3. [[Incident Management]] - 28 links

Link Health Status: ✓ Excellent (99.5% valid)

When to Use:

• Periodic health checks (weekly/monthly)
• Before major wiki restructuring
• Assessing wiki growth and connectivity

---

Missing Links Only Mode

Purpose: Quick scan for broken links without full validation output.

Usage:

logseq-validate-links missing

Output:

Missing Pages:
- [[New Concept]]
- [[Technical Topic]]
- [[Research Area]]

When to Use:

• Quick check after bulk edits
• Pre-commit validation
• Scripting/automation

---

Edge Cases and Error Handling

Tool Not Found

Issue: logseq-validate-links command not available Action:

1. Check if package installed: which logseq-validate-links
2. If not found, install: cd ~/Documents/personal-wiki && uv install -e .
3. Verify: logseq-validate-links --help
4. Report if installation fails

Empty Wiki

Issue: No markdown files found in pages/journals Action:

1. Verify paths: ls ~/Documents/personal-wiki/logseq/pages/
2. Report: "No markdown files found. Wiki appears empty or path incorrect."
3. Ask user to confirm wiki location

Permission Errors

Issue: Cannot read files or create stubs Action:

1. Check permissions: ls -la ~/Documents/personal-wiki/logseq/pages/
2. Report specific permission issues
3. Suggest: chmod commands or running with appropriate permissions

Filename Conflicts

Issue: Stub would overwrite existing file (rare edge case) Action:

1. Skip stub creation for conflicting file
2. Report: "Skipped [[Page Name]] - file exists but link not resolving (filename mismatch?)"
3. Suggest manual review

Special Characters in Page Names

Issue: Links contain characters invalid for filenames Action:

1. Sanitize filename (replace invalid characters)
2. Create stub with sanitized name
3. Report mapping: [[Page/Name]] → Page_Name.md

---

Usage Examples

Example 1: Basic Validation (Report Only)

Command: /knowledge/validate-links

Execution:

cd ~/Documents/personal-wiki
logseq-validate-links validate

Output:

Scanning 245 files...

🔗 Broken Links Found (3):

High Priority (multiple references):
- [[Database Sharding]] → Referenced in: Performance.md, Scaling.md, 2025_10_15.md

Medium Priority (journals):
- [[Incident Response Playbook]] → Referenced in: 2025_10_20.md

Low Priority (single reference):
- [[Old Framework]] → Referenced in: Archive.md

Potential Typos:
- [[Kuberntes]] → Did you mean [[Kubernetes]]? (in Infrastructure.md)

📊 Summary:
- Total links: 423
- Valid: 420 (99.3%)
- Broken: 3 (0.7%)
- Potential typos: 1

✓ Validation complete. Run with auto_fix to create stubs.

Claude Response:

## Link Validation Results

Found 3 broken links in your wiki:

**High Priority**:
- [[Database Sharding]] - Create this page (referenced in 3 files)

**Medium Priority**:
- [[Incident Response Playbook]] - Recent journal reference

**Low Priority**:
- [[Old Framework]] - Appears in archived content

**Potential Typo**:
- [[Kuberntes]] → [[Kubernetes]] in Infrastructure.md

**Recommendations**:
1. Create [[Database Sharding]] page (high value, multiple references)
2. Fix [[Kuberntes]] typo manually
3. Consider if [[Old Framework]] is still relevant

Run `/knowledge/validate-links all true` to auto-create stubs for all broken links.

---

Example 2: Automatic Stub Creation

Command: /knowledge/validate-links all true

Execution:

cd ~/Documents/personal-wiki
logseq-validate-links validate --create-missing

Output:

Scanning 245 files...
Found 3 broken links.

Creating stub pages...
✓ Created: Database Sharding.md
✓ Created: Incident Response Playbook.md
✓ Created: Old Framework.md

Re-validating...
✓ All links now valid!

📊 Summary:
- Stubs created: 3
- Broken links resolved: 3
- Remaining issues: 0

Next steps:
- Review stub pages and add content
- Consider using /process-journal-zettels for research-backed content

Claude Response:

## Stubs Created Successfully

Created 3 stub pages to resolve broken links:

1. **Database Sharding.md**
   - Referenced in: Performance.md, Scaling.md, 2025_10_15.md
   - High priority - add comprehensive content

2. **Incident Response Playbook.md**
   - Referenced in: 2025_10_20.md
   - Recent work - fill in details

3. **Old Framework.md**
   - Referenced in: Archive.md
   - Low priority - review if still relevant

**Next Steps**:
1. Review these stubs and add meaningful content
2. Use `/knowledge/process-journal-zettels 2025_10_15` to research Database Sharding
3. Consider creating Incident Response Playbook based on recent experiences

All links now validate successfully ✓

---

Example 3: Selective Stub Creation (High Priority Only)

Command: /knowledge/validate-links selective true

Execution:

# Run validation first
logseq-validate-links validate

# Manually create only high-priority stubs (multi-referenced)
# Create stub for Database Sharding (3 references)

Output:

Scanning 245 files...
Found 3 broken links.

Creating selective stubs (high-priority only)...
✓ Created: Database Sharding.md (3 references)
⊘ Skipped: Incident Response Playbook.md (1 reference)
⊘ Skipped: Old Framework.md (1 reference)

Re-validating...
⚠ 2 broken links remain (low-priority)

📊 Summary:
- High-priority stubs created: 1
- Remaining broken links: 2 (low priority)

Claude Response:

## Selective Stubs Created

Created stubs for high-priority links only:

**Created**:
- [[Database Sharding]] (3 references) - Priority: High

**Remaining Broken Links** (low priority):
- [[Incident Response Playbook]] (1 reference) - Journal entry
- [[Old Framework]] (1 reference) - Archived content

**Recommendation**:
Focus on completing [[Database Sharding]] content first (multiple references indicate importance).
Address remaining links as needed or run `/knowledge/validate-links all true` to create all stubs.

---

Example 4: Statistics Check

Command: /knowledge/validate-links stats

Execution:

logseq-validate-links stats

Output:

📊 Wiki Statistics

Overall Health:
- Total pages: 156
- Total journals: 245
- Unique links: 423
- Unique tags: 78
- Broken links: 0 (0%)

Most Connected Pages (outbound links):
1. [[Platform Engineering]] - 45 links
2. [[Database Design]] - 32 links
3. [[Incident Management]] - 28 links
4. [[System Architecture]] - 24 links
5. [[Performance Optimization]] - 21 links

Link Health Status: ✓ Excellent (100% valid)
Connectivity: ✓ Good (avg 2.7 links/page)

Claude Response:

## Wiki Health Report

Your personal wiki is in excellent health!

**Metrics**:
- 156 pages, 245 journal entries
- 423 unique links, 78 tags
- 0 broken links (100% valid) ✓

**Most Connected Topics**:
Your knowledge graph has strong clusters around:
1. Platform Engineering (45 connections)
2. Database Design (32 connections)
3. Incident Management (28 connections)

**Analysis**:
- High connectivity (2.7 links/page average)
- No broken references
- Well-structured knowledge graph

No action needed. Continue building your knowledge base!

---

Example 5: Post-Bulk-Edit Validation

Scenario: After renaming several pages or restructuring wiki

Command: /knowledge/validate-links

Execution:

logseq-validate-links validate

Output:

Scanning 245 files...

🔗 Broken Links Found (8):

Likely due to recent page renames:
- [[Old Page Name]] → Not found (referenced in 5 files)
- [[Another Old Name]] → Not found (referenced in 3 files)

Potential fixes:
- [[Old Page Name]] → [[New Page Name]]? (New Page Name.md exists)
- [[Another Old Name]] → [[Renamed Page]]? (Renamed Page.md exists)

📊 Summary:
- Broken: 8
- Potential renames detected: 2

Claude Response:

## Validation After Restructuring

Detected broken links likely caused by recent page renames:

**Action Needed**:
1. Update links in 5 files: [[Old Page Name]] → [[New Page Name]]
2. Update links in 3 files: [[Another Old Name]] → [[Renamed Page]]

**Options**:
A) Fix manually using search/replace
B) Create redirect stubs (Old Page Name.md with link to new name)
C) Use /knowledge/validate-links to create stubs, then merge content

**Recommendation**: Update links to reflect new page names for clean references.

Would you like me to help update these links across your wiki?

---

Integration Patterns

Pre-Commit Hook Integration

Add to .git/hooks/pre-commit in wiki repository:

#!/bin/bash
cd ~/Documents/personal-wiki
logseq-validate-links validate --exit-code
if [ $? -eq 1 ]; then
    echo "❌ Commit blocked: Broken links found"
    echo "Fix links or run 'logseq-validate-links validate --create-missing'"
    exit 1
fi

Periodic Health Checks

Add to cron for weekly validation:

# Every Sunday at 9 AM
0 9 * * 0 cd ~/Documents/personal-wiki && logseq-validate-links stats > /tmp/wiki_health.txt

CI/CD Validation (GitHub Actions)

name: Validate Wiki Links
on: [push, pull_request]
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install dependencies
        run: uv install -e .
      - name: Validate links
        run: logseq-validate-links validate

---

Quality Standards

All validation must satisfy:

1. Completeness:

   • All markdown files scanned (pages + journals)
   • All link types validated ([[links]] and #[[tags]])
   • No false positives or missed broken links

2. Accuracy:

   • Filename matching handles case and special characters
   • Typo detection uses reasonable similarity threshold
   • Priority categorization reflects actual reference patterns

3. Actionability:

   • Clear recommendations provided
   • Stub templates are comprehensive and consistent
   • Next steps explicitly stated

4. Safety:

   • Stub creation never overwrites existing files
   • Original content never modified (only new files created)
   • Validation is non-destructive

5. Reporting:

   • Summary includes all key metrics
   • Broken links grouped by priority
   • Files created documented with full paths

---

Command Invocation

Format: /knowledge/validate-links [mode] [auto_fix]

Arguments:

• mode (optional): Validation mode
  • validate (default): Full validation with reporting
  • stats: High-level statistics only
  • missing: Quick list of broken links
  • selective: Process high-priority links only
• auto_fix (optional): Automatic stub creation
  • true or all: Create stubs for all broken links
  • false (default): Report only, no stub creation
  • selective: Create stubs only for multi-referenced pages

Execution Mode: Direct execution using logseq-validate-links CLI tool

Expected Duration: 5-30 seconds depending on wiki size

Prerequisites:

• stapler_logseq_tools package installed (uv install -e .)
• Read access to logseq/pages and logseq/journals directories
• Write access to logseq/pages if creating stubs