index-docs

Roger-Parkinson-EHP's avatarfrom Roger-Parkinson-EHP

Index markdown documentation - headings, diagrams, tables, code blocks, links. Use for quick overview without reading full files.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 2, 2026
[Files and Documents]

When & Why to Use This Skill

The Markdown Documentation Indexer is a high-efficiency Claude skill designed to extract structural metadata from Markdown files without loading full content. By leveraging optimized Bash commands, it parses headings, Mermaid diagrams, code blocks, tables, and links to provide a comprehensive architectural overview. This tool is essential for navigating large documentation sets while maintaining token efficiency and providing a clear map of project resources for AI agents.

Use Cases

  • Project Onboarding: Rapidly understand the hierarchy of a new codebase by indexing all H1 and H2 headings across the documentation folder.
  • Technical Asset Discovery: Locate and categorize all Mermaid diagrams, code blocks, and tables across hundreds of files to assess technical depth.
  • Documentation Maintenance: Scan an entire repository for TODO, FIXME, and XXX tags to identify pending tasks or technical debt within docs.
  • Token Optimization: Generate a structural map of large documents to identify relevant sections before performing a full-file read, significantly reducing context window usage.
  • Link & Reference Auditing: Extract and review all internal cross-references and external URLs to ensure documentation integrity and find broken links.
nameindex-docs
descriptionIndex markdown documentation - headings, diagrams, tables, code blocks, links. Use for quick overview without reading full files.
allowed-toolsBash, Read

Markdown Documentation Indexer

Extract structure from markdown files without loading full content.

Quick Start

Headings (Most Common)

# H1/H2 headings
find . -name "*.md" -type f -not -path "*/.git/*" | xargs grep -n "^##\? " 2>/dev/null | head -100

# H1/H2/H3 headings
find . -name "*.md" -type f -not -path "*/.git/*" | xargs grep -n "^###\?\? " 2>/dev/null | head -150

Mermaid Diagrams

# Find files with mermaid diagrams
grep -rln 'mermaid' --include="*.md" . 2>/dev/null

# Show mermaid diagram types
grep -rn 'mermaid' --include="*.md" -A1 . 2>/dev/null | grep -E "(flowchart|graph|sequenceDiagram|classDiagram|erDiagram|gantt)"

Code Blocks

# Find all code blocks with language
grep -rn '^```[a-z]' --include="*.md" . 2>/dev/null | head -50

# Count code blocks by language
grep -roh '^```[a-z]*' --include="*.md" . 2>/dev/null | sort | uniq -c | sort -rn

Tables

# Find markdown tables (header lines)
grep -rn "^|.*|.*|$" --include="*.md" . 2>/dev/null | grep -E "\-\-\-" | head -30

# Find all links
grep -ron "\[.*\](.*)" --include="*.md" . 2>/dev/null | head -50

# Find cross-references (relative links)
grep -ron "\[.*\](\.\./.*)" --include="*.md" . 2>/dev/null | head -30

# Find external links
grep -ron "\[.*\](https://.*)" --include="*.md" . 2>/dev/null | head -30

Images

# Find all images
grep -ron "!\[.*\](.*)" --include="*.md" . 2>/dev/null | head -30

YAML Frontmatter

# Find files with frontmatter
grep -rln "^---$" --include="*.md" . 2>/dev/null | head -20

TODOs and FIXMEs

# Find action items in docs
grep -rn "TODO\|FIXME\|XXX\|\[ \]" --include="*.md" . 2>/dev/null | head -30

Filtered Searches

# Specific folder only
find ./4-The-Plan -name "*.md" | xargs grep -n "^##\? " 2>/dev/null

# Exclude archives
find . -name "*.md" -type f -not -path "*/archive/*" -not -path "*/z-*" | xargs grep -n "^##\? " 2>/dev/null | head -100

# Topic-specific (pipe to grep)
find . -name "*.md" | xargs grep -n "^##\? " 2>/dev/null | grep -i "security\|auth"

Pattern Reference

What Command
H1 only grep -rn "^# " --include="*.md"
H2 only grep -rn "^## " --include="*.md"
Mermaid grep -rln "mermaid" --include="*.md"
Code blocks grep -rn '^```[a-z]' --include="*.md"
Tables `grep -rn "^
Links grep -ron "\[.*\](.*)" --include="*.md"
TODOs grep -rn "TODO|FIXME" --include="*.md"

Token Efficiency

All commands return summaries, not full files. A complete doc index typically uses <200 tokens while giving you the map to know what to read next.

  • startup: Full session bootstrap
  • codebase-index: Code architecture discovery
  • search-history: Conversation context