Skip to main content

/markdown-cleanup - Documentation Quality Assurance

Comprehensive markdown cleanup that audits, fixes, and optimizes documentation for GitHub compatibility and visual clarity.

Usage​

# Audit specific file or directory
/markdown-cleanup internal/architecture/adrs/

# Fix issues automatically
/markdown-cleanup docs/ --fix

# Convert ASCII diagrams to mermaid
/markdown-cleanup README.md --ascii-to-mermaid

# Full cleanup with all options
/markdown-cleanup . --fix --ascii-to-mermaid

What It Does​

1. Audit Phase​

Checks for:

  • Broken mermaid diagrams
  • GitHub-incompatible HTML tags
  • Unclosed code blocks
  • Trailing whitespace
  • ASCII diagrams convertible to mermaid

2. Fix Phase​

Automatically fixes:

  • <br> → <br/> in mermaid
  • Trailing whitespace removal
  • HTML entity conversion (&nbsp; → space)
  • Final newline addition

3. Optimization Phase​

  • Converts ASCII diagrams to mermaid
  • Validates mermaid syntax
  • Adds proper frontmatter
  • Cross-links related documents

Examples​

Fix ADR Documentation​

/markdown-cleanup internal/architecture/adrs/ADR-190-cross-llm-bridge-architecture.md --fix

Clean All Documentation​

/markdown-cleanup docs/ --fix

Convert Diagrams​

/markdown-cleanup README.md --ascii-to-mermaid

Implementation​

#!/usr/bin/env bash

# Step 1: Audit
python3 scripts/audit-markdown.py "$1"

# Step 2: Fix (if --fix flag)
if [ "$2" == "--fix" ]; then
    python3 scripts/fix-markdown-issues.py "$1"
fi

# Step 3: Classify updates
/classify "$1"

# Step 4: Log work
/session-log "Markdown cleanup: $1"
  • /classify - Re-classify documents after changes
  • /session-log - Log cleanup activity
  • /component-stats - View documentation statistics
  • markdown-mermaid-best-practices - Best practices guide
  • markdown-mermaid-cleaner - Specialized cleanup agent