split-markdown

Intelligently split a large markdown file into context-friendly sections with automatic table of contents and navigation.

Usage

# Split a specific markdown file
/guard:split-markdown <file-path>

# Examples
/guard:split-markdown task.md
/guard:split-markdown docs/PRD.md
/guard:split-markdown ./planning/requirements.md

What It Does

When you split a markdown file, the Guard plugin will:

1. Analyze Structure - Parse the document to identify logical sections based on headers
2. Propose Split - Show you how the file will be divided before making changes
3. Create Index - Generate 00-<basename>.md with table of contents and navigation
4. Create Sections - Generate numbered files (01-, 02-, etc.) for each section
5. Add Navigation - Include bidirectional links between index and sections
6. Backup Original - Save the original file as <filename>.backup

Output Structure

For a file named task.md, you'll get:

task.md.backup          # Original file (backup)
00-task.md              # Index with TOC
01-task.md              # First section
02-task.md              # Second section
03-task.md              # Third section
...

Index File (00-task.md)

Contains:

• Document title
• Table of contents with links to all sections
• Quick navigation statistics (total sections, line counts)
• Overview explaining why the split was done
• Metadata (split date, strategy used)

Section Files (01-task.md, 02-task.md, etc.)

Each section includes:

• Section title
• Navigation header (links to index, previous, next)
• Full section content (preserved formatting)
• Navigation footer (same links as header)

Configuration

The splitting behavior is controlled by .claude/quality_config.json:

{
  "markdown_splitter": {
    "enabled": true,
    "auto_suggest_threshold": 2000,
    "target_chunk_size": 800,
    "split_strategy": "headers",
    "preserve_original": true,
    "create_index": true
  }
}

Configuration Options

• auto_suggest_threshold (default: 2000)

  • Line count threshold for automatic split suggestions
  • When a markdown file exceeds this, Guard will offer to split it

• target_chunk_size (default: 800)

  • Target lines per section (used with "smart" strategy)
  • Helps keep sections at manageable sizes

• split_strategy (default: "headers")

  • "headers" - Split at each top-level header (# title)
  • "smart" - Group sections to target chunk size while respecting boundaries

• preserve_original (default: true)

  • Keep backup of original file as <filename>.backup
  • Set to false to remove original after split

• create_index (default: true)

  • Generate 00-<basename>.md index file
  • Set to false to only create section files

Split Strategies

Headers Strategy (Default)

Splits at every top-level header (# Title):

Pros:

• Preserves logical document structure
• Sections are semantically meaningful
• Easy to understand split points

Cons:

• May create uneven section sizes

Best for:

• Well-structured documents with clear top-level sections
• PRDs, design docs, technical specifications

Smart Strategy

Groups sections to target chunk size while respecting header boundaries:

Pros:

• More consistent section sizes
• Still respects logical boundaries
• Better for documents with many small sections

Cons:

• May group unrelated content together

Best for:

• Documents with many small sections
• Task lists with many items
• API documentation with many endpoints

Examples

Example 1: Large PRD Document

/guard:split-markdown requirements.md

Before:

requirements.md (3500 lines)
  # Overview
  # User Stories
  # Technical Requirements
  # Architecture
  # Testing Strategy

After:

requirements.md.backup
00-requirements.md (index)
01-requirements.md (Overview - 400 lines)
02-requirements.md (User Stories - 900 lines)
03-requirements.md (Technical Requirements - 1100 lines)
04-requirements.md (Architecture - 700 lines)
05-requirements.md (Testing Strategy - 400 lines)

Example 2: Implementation Task List

/guard:split-markdown tasks.md

Before:

tasks.md (4200 lines)
  # Backend Tasks
    ## API Endpoints (many subtasks)
    ## Database Schema (many subtasks)
  # Frontend Tasks
    ## Components (many subtasks)
    ## Pages (many subtasks)

After:

tasks.md.backup
00-tasks.md (index)
01-tasks.md (Backend Tasks - 2100 lines)
02-tasks.md (Frontend Tasks - 2100 lines)

Example 3: API Documentation

/guard:split-markdown api-docs.md

With "split_strategy": "smart" in config:

Before:

api-docs.md (5000 lines)
  # Authentication
  # User Endpoints (50+ endpoints)
  # Data Endpoints (40+ endpoints)
  # Admin Endpoints (30+ endpoints)

After:

api-docs.backup
00-api-docs.md (index)
01-api-docs.md (Authentication - 600 lines)
02-api-docs.md (User Endpoints Part 1 - 800 lines)
03-api-docs.md (User Endpoints Part 2 - 850 lines)
04-api-docs.md (Data Endpoints Part 1 - 800 lines)
05-api-docs.md (Data Endpoints Part 2 - 750 lines)
06-api-docs.md (Admin Endpoints - 700 lines)

When to Use

Split a markdown file when:

• 📄 File exceeds 2000 lines - May hit LLM context limits
• 🔍 Hard to navigate - Takes too long to find sections
• ⚡ Performance issues - Editor or tools slow down with large file
• 👥 Team collaboration - Easier to work on separate sections
• 📝 Documentation - Better organization for large docs

Integration with Guard

The markdown splitter integrates with Guard's file size checking:

1. When you try to write a large markdown file (>2000 lines)
2. Guard detects it exceeds the threshold
3. Guard offers: "This file is large. Would you like to split it?"
4. If you say "yes", the markdown-splitter agent is automatically launched
5. The agent analyzes, proposes a split, and executes with your approval

This provides proactive splitting suggestions without manual command invocation.

Implementation

This command launches the markdown-splitter agent with the specified file:

# The agent will:
# 1. Read and analyze the file structure
# 2. Present a proposed split plan
# 3. Ask for confirmation
# 4. Execute the split using split_markdown.py
# 5. Verify results and report success

Tips

1. Review before splitting - Always check the proposed split plan
2. Adjust strategy - Switch between "headers" and "smart" for different results
3. Update references - If other files link to the original, update them
4. Commit original first - Use git to track changes before splitting
5. Test navigation - After splitting, click through a few section links

Related Commands

• /guard:config - View and configure splitting thresholds
• /guard:init - Initialize Guard with default configuration

See Also

• markdown-splitter agent - The AI agent that performs the analysis and splitting
• split_markdown.py - The underlying Python script
• .claude/quality_config.json - Configuration file

---

Need help? The markdown-splitter agent will guide you through the process and explain each step.