Markdown Validation

This skill provides comprehensive markdown validation capabilities for documentation files.

When to Use

Use markdown-validation when:

1. Validating markdown files for syntax and formatting errors
2. Checking documentation quality after edits
3. Enforcing documentation standards across the project
4. Identifying broken links or invalid references
5. Reviewing markdown files before commits

Validation Checks

1. Syntax Validation

• Valid markdown syntax
• Proper header hierarchy (no skipped levels)
• Balanced code fences
• Correct list formatting
• Proper link syntax

2. Link Validation

• Internal links point to existing files
• Anchor links match actual headers
• No broken external links (when network available)

3. Formatting Standards

• Consistent heading styles
• Proper code block language tags
• Table formatting correctness
• No trailing whitespace
• Consistent list markers

4. Documentation Quality

• Files have descriptive headers
• Code examples are complete
• Links are descriptive (not "click here")
• Tables have headers
• Proper frontmatter when required

Usage

Automatic Validation

The validation script runs automatically when triggered by hooks on markdown file edits.

Manual Validation

Validate a single file:

./docs/skills/markdown-validation/scripts/validate-markdown.py path/to/file.md

Validate multiple files:

./docs/skills/markdown-validation/scripts/validate-markdown.py file1.md file2.md file3.md

Validate a directory:

find docs/ -name "*.md" -exec ./docs/skills/markdown-validation/scripts/validate-markdown.py {} +

Output Format

Validation results are returned in structured format:

✅ path/to/file.md - PASS

❌ path/to/other.md - FAIL
  Line 15: Header level skipped (h1 -> h3)
  Line 42: Broken internal link: [docs/missing.md](docs/missing.md)
  Line 87: Unclosed code fence

Integration with Hooks

This skill works best when integrated with PostToolUse hooks:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q '\\.md\"'; then $CLAUDE_PROJECT_DIR/docs/skills/markdown-validation/scripts/validate-markdown.py \"$(echo \"$CLAUDE_TOOL_INPUT\" | grep -o '\"[^\"]*\\.md\"' | tr -d '\"')\"; fi"
        }]
      }
    ]
  }
}

Common Issues and Fixes

Issue: Header Level Skipped

Problem: # Header 1 followed by ### Header 3 (skipped h2) Fix: Maintain sequential header hierarchy

Issue: Broken Internal Link

Problem: Link points to non-existent file Fix: Update link target or create missing file

Issue: Unclosed Code Fence

Problem: `` opened but not closed Fix: Add closing `` after code block

Issue: No Language Tag

Problem: Code fence missing language identifier Fix: Add language: ``python, `bash, ``javascript

Configuration

Create .markdown-validation.json in project root to customize validation:

{
  "checkLinks": true,
  "checkSyntax": true,
  "requireFrontmatter": false,
  "allowedHeaderLevels": [1, 2, 3, 4, 5, 6],
  "requireLanguageTags": true,
  "maxLineLength": null
}

References

• Markdown Specification: See references/markdown-spec.md
• Project Standards: See references/documentation-standards.md