markdown-crossref-validator

Markdown Cross-Reference Validator

Safety Notice

This listing is imported from skills.sh public index metadata. Review upstream SKILL.md and repository scripts before running.

Copy this and send it to your AI assistant to learn

Install skill "markdown-crossref-validator" with this command: npx skills add prulloac/agent-skills/prulloac-agent-skills-markdown-crossref-validator

Markdown Cross-Reference Validator

When to use this skill

Use this skill when the user asks to validate or check cross-references in markdown files. This includes verifying that internal links (e.g., text) point to existing headings, and that file references (e.g., text) point to existing files.

Algorithm & Workflow

Phase 1: Document Preparation

  • Identify target file(s): Determine which markdown file(s) to validate

  • Read content: Load the full markdown document(s) into memory

  • Establish base path: Determine the root directory for relative file references

Phase 2: Heading Extraction

  • Scan for headings: Find all lines matching regex ^#+\s+(.*)$

  • Build anchor map: For each heading:

  • Extract heading text: # Introduction → Introduction

  • Convert to anchor ID: lowercase, replace spaces with hyphens, remove special chars

  • Store mapping: introduction → heading level (1-6)

  • Handle special cases: Account for heading IDs, custom anchors using HTML comments

  • Normalize anchors: Ensure consistent anchor formatting for comparison

Phase 3: Link Extraction

  • Find all link patterns:

  • Inline links: text using regex [([^]]+)](([^)]+))

  • Reference links: text using regex [([^]]+)][([^]]+)]

  • Reference definitions: ref: url using regex ^\s*[([^]]+)]:\s*(.+)$

  • HTML links: <a href="url">text</a>

  • Categorize links:

  • Internal anchors: #heading-name

  • File references: path/to/file.md

  • Combined: path/to/file.md#section

  • External: http://... , https://...

  • Relative path: ../other.md

Phase 4: Link Validation

For Internal Anchor Links (#anchor )

  • Extract anchor identifier

  • Normalize anchor (lowercase, hyphenate)

  • Check against anchor map from Phase 2

  • Record as ✓ Valid or ✗ Broken

For File References (path/to/file.md )

  • Resolve relative path from current document location

  • Check file existence in project

  • If file + anchor (path/to/file.md#section ):

  • Verify file exists

  • Parse target file for headings

  • Verify anchor exists in target file

  • Record as ✓ Valid or ✗ Broken with reason

For External Links (http:// , https:// )

  • Mark as external (scope: not validated for internal consistency)

  • Optionally note for manual review

Phase 5: Issue Categorization

Classify all broken references by type:

  • Missing Heading: Anchor exists but no matching heading in file

  • Missing File: File reference path doesn't exist

  • Invalid Anchor in Target: File exists but referenced section doesn't

  • Malformed Reference: Link syntax is invalid or unparseable

Phase 6: Report Generation

  • Create summary: Total links checked, valid count, broken count, broken percentage

  • Group issues: Organize by file and issue type

  • Provide context: Show the line number and actual link text

  • Suggest fixes: Recommend corrected anchor names or file paths

  • Verify output: Ensure report is complete and accurate

Validation & Verification

Validation Checklist

  • ✅ All markdown files are readable and parseable

  • ✅ All heading anchors are properly extracted and normalized

  • ✅ All link patterns (inline, reference, HTML) are detected

  • ✅ Internal anchor references are validated

  • ✅ File references exist and are properly resolved

  • ✅ Cross-file anchors are verified in target files

  • ✅ Report categorizes all issues by type

  • ✅ All broken references are identified with context

Report Verification Steps

  • Random sample 5-10 links and manually verify they match report findings

  • Check that issue count matches actual broken references

  • Verify all line numbers and file paths are accurate

  • Confirm suggestions for fixes are actionable

Concrete Examples

Example 1: Simple Document with Internal Links

Input: docs/guide.md

Getting Started Guide

Table of Contents

Installation

Follow these steps to install...

Configuration

See Installation for prerequisites.

Advanced Setup

For complex scenarios, refer to Config.

Troubleshooting

Check Non-existent Section for help.

Validation Report:

═══════════════════════════════════════════════════════════ MARKDOWN CROSS-REFERENCE VALIDATION REPORT ═══════════════════════════════════════════════════════════

File: docs/guide.md Scan Date: 2024-02-21 Status: ✓ VALIDATED WITH ISSUES

─────────────────────────────────────────────────────────── SUMMARY ─────────────────────────────────────────────────────────── Total Links Found: 5 Valid References: 4 Broken References: 1 Validation Rate: 80%

─────────────────────────────────────────────────────────── VALID REFERENCES ✓ ───────────────────────────────────────────────────────────

✓ Line 4: Installation Type: Internal anchor Status: Heading "Installation" found at line 11

✓ Line 5: Configuration Type: Internal anchor Status: Heading "Configuration" found at line 18

✓ Line 5: Advanced Setup Type: Internal anchor Status: Heading "Advanced Setup" found at line 22

✓ Line 19: Installation Type: Internal anchor (cross-reference) Status: Valid, heading exists

─────────────────────────────────────────────────────────── BROKEN REFERENCES ✗ ───────────────────────────────────────────────────────────

✗ Line 26: Non-existent Section Type: Internal anchor Issue: MISSING HEADING Anchor: #missing-section Status: No heading found matching "missing-section"

Suggestion: Available sections in document: - #getting-started-guide (h1) - #table-of-contents (h2) - #installation (h2) - #configuration (h2) - #advanced-setup (h2) - #troubleshooting (h2)

─────────────────────────────────────────────────────────── ANCHOR MAPPING ─────────────────────────────────────────────────────────── getting-started-guide (Level 1) → Line 1 table-of-contents (Level 2) → Line 3 installation (Level 2) → Line 11 configuration (Level 2) → Line 18 advanced-setup (Level 2) → Line 22 troubleshooting (Level 2) → Line 25

═══════════════════════════════════════════════════════════

Example 2: Cross-File References

Input: Multiple files in docs/ directory

Files:

  • docs/index.md

  • Main documentation index

  • docs/guide/installation.md

  • Installation guide

  • docs/guide/config.md

  • Configuration guide

  • docs/api/endpoints.md

  • API reference

Content: docs/index.md

Documentation Index

Quick Start

See Installation for details.

Validation Report:

═══════════════════════════════════════════════════════════ MARKDOWN CROSS-REFERENCE VALIDATION REPORT ═══════════════════════════════════════════════════════════

File: docs/index.md Scan Date: 2024-02-21 Status: ⚠ VALIDATED WITH CRITICAL ISSUES

─────────────────────────────────────────────────────────── SUMMARY ─────────────────────────────────────────────────────────── Total Links Found: 6 Valid References: 3 Broken References: 3 Validation Rate: 50%

─────────────────────────────────────────────────────────── VALID REFERENCES ✓ ───────────────────────────────────────────────────────────

✓ Line 3: Installation Guide Type: File reference Path: docs/guide/installation.md Status: File exists (2.5 KB)

✓ Line 4: Configuration Type: File with anchor Path: docs/guide/config.md Anchor: #configuration Status: File exists, heading found in target

✓ Line 8: Installation Type: File with anchor Path: docs/guide/installation.md Anchor: #system-requirements Status: File exists, heading found in target

─────────────────────────────────────────────────────────── BROKEN REFERENCES ✗ ───────────────────────────────────────────────────────────

✗ Line 5: API Reference Type: File reference Issue: MISSING FILE Path: docs/api/endpoints.md Status: File not found in project

Suggestion: Did you mean? - docs/api/reference.md (exists) - docs/endpoints.md (exists)

✗ Line 6: Getting Help Type: File reference Issue: MISSING FILE Path: docs/support/help.md Status: File not found in project

Suggestion: No similar files found. Check path spelling.

✗ Line 7: Basic Setup Type: Internal anchor Issue: MISSING HEADING Anchor: #quick-start Status: Anchor not found (likely typo: #quickstart exists)

Suggestion: Did you mean #quickstart?

─────────────────────────────────────────────────────────── CROSS-FILE ANALYSIS ───────────────────────────────────────────────────────────

Scanned 4 files in project:

  • docs/index.md (6 links)
  • docs/guide/installation.md (12 links, all valid)
  • docs/guide/config.md (8 links, 1 broken)
  • docs/api/reference.md (5 links, all valid)

Cross-file reference summary:

  • Files referenced: 4
  • Valid file references: 3
  • Invalid file references: 2
  • Unresolvable anchors in targets: 0

═══════════════════════════════════════════════════════════

Example 3: Reference-Style Links

Input: docs/readme.md

Project Documentation

See the Getting Started guide for setup instructions.

For API details, check API Reference or CLI Reference.

Invalid reference: [Missing Reference][unknown]

Validation Report:

═══════════════════════════════════════════════════════════ MARKDOWN CROSS-REFERENCE VALIDATION REPORT ═══════════════════════════════════════════════════════════

File: docs/readme.md Scan Date: 2024-02-21 Type: Reference-style links Status: ✓ VALIDATED WITH ISSUES

─────────────────────────────────────────────────────────── SUMMARY ─────────────────────────────────────────────────────────── Total Links Found: 4 Valid References: 3 Broken References: 1 External Links: 1 Validation Rate: 75%

─────────────────────────────────────────────────────────── REFERENCE DEFINITIONS FOUND ───────────────────────────────────────────────────────────

gs → guide/getting-started.md#prerequisites (Line 9) api → https://api.example.com (Line 10, External) cli → guide/cli.md#commands (Line 11)

─────────────────────────────────────────────────────────── VALIDATION RESULTS ───────────────────────────────────────────────────────────

✓ Getting Started (Line 3) Reference defined: Yes Target: guide/getting-started.md#prerequisites File status: Exists Anchor status: Valid Result: VALID

✓ API Reference (Line 5) Reference defined: Yes Target: https://api.example.com Type: External URL Result: EXTERNAL (not validated)

✓ CLI Reference (Line 5) Reference defined: Yes Target: guide/cli.md#commands File status: Exists Anchor status: Valid Result: VALID

✗ [Missing Reference][unknown] (Line 7) Reference defined: No Status: UNDEFINED REFERENCE Issue: Reference label "[unknown]" not found in definitions

Suggestion: Available references in document: - gs - api - cli

═══════════════════════════════════════════════════════════

Tools to use

  • Use file reading tools to access markdown files.

  • Use grep or parsing to extract links and headings.

  • For file existence, use directory listing tools.

Quick Reference: Link Patterns

Pattern Example Type

Inline link text

Internal anchor

Inline file text

File reference

Combined text

File with anchor

Reference-style text

Reference link

HTML link <a href="#id">text</a>

HTML anchor

External text

External URL

Source Transparency

This detail page is rendered from real SKILL.md content. Trust labels are metadata-based hints, not a safety guarantee.

Open in GitHubOpen in ClawHub

Related Skills

Related by shared tags or category signals.

Automation

custom-agent-creator

No summary provided by upstream source.

Repository SourceNeeds Review
-17
prulloac
Automation

semver-changelog

No summary provided by upstream source.

Repository SourceNeeds Review
-12
prulloac
Automation

git-commit-workflow

No summary provided by upstream source.

Repository SourceNeeds Review
-11
prulloac