md-splitter

name

md-splitter

description

Split large markdown files into multiple smaller files based on their table of contents or heading structure. Creates individual markdown files for each chapter/section in a new folder. Use when user requests to split, divide, break up, or separate a markdown file into chapters, sections, or multiple files. Trigger phrases include "split markdown by chapters", "divide md file into sections", "create separate files from TOC", "break up large markdown", or when working with large markdown documents that need to be organized into manageable parts.

Markdown Splitter by Table of Contents

Overview

Splits large markdown files into multiple smaller files based on their structure. Detects table of contents or heading hierarchy and creates individual markdown files for each major section/chapter. Organizes output files in a dedicated folder named after the source file.

Quick Start

Basic usage:

cd .github\skills\md-splitter\scripts
.\Split-Markdown.ps1 -MarkdownPath "C:\path\to\document.md"

Specify custom heading level:

.\Split-Markdown.ps1 -MarkdownPath "C:\path\to\document.md" -SplitLevel 1

Output: Creates folder document\ with individual markdown files for each section

Prerequisites

• PowerShell 5.1 or later
• Read access to source markdown file
• Write access to create output folder
• Well-structured markdown with consistent heading hierarchy

Core Workflow

The script performs these steps automatically:

1. Analyze Markdown Structure

   • Reads the entire markdown file
   • Detects table of contents (if present)
   • Analyzes heading hierarchy (H1, H2, H3, etc.)
   • Determines optimal split level

2. Parse Content Sections

   • Identifies all top-level sections/chapters
   • Extracts content for each section
   • Preserves formatting, code blocks, and lists
   • Maintains markdown structure

3. Generate Output Files

   • Creates output folder named after source file (without extension)
   • Generates individual markdown files for each section
   • Uses sanitized section names for filenames
   • Adds metadata header to each file

4. Create Index File

   • Generates _index.md with links to all sections
   • Preserves table of contents structure
   • Provides navigation between files

5. Report Results

   • Displays statistics (sections created, output folder)
   • Lists all generated files
   • Opens output folder in Windows Explorer (optional)

Usage Examples

Example 1: Split by chapters

.\Split-Markdown.ps1 -MarkdownPath ".\docs\Book.md"
# Creates: .\docs\Book\01-chapter-one.md, 02-chapter-two.md, etc.

Example 2: Split PDF extraction

# After extracting PDF to markdown
.\Split-Markdown.ps1 -MarkdownPath ".\PDFDocumentation\Programming BC.md"
# Creates: .\PDFDocumentation\Programming BC\01-introduction.md, etc.

Example 3: Custom split level (H2 headings)

.\Split-Markdown.ps1 -MarkdownPath ".\docs\manual.md" -SplitLevel 2
# Splits on ## headings instead of # headings

Script Parameters

-MarkdownPath <string>
    Path to the markdown file to split (required)

-SplitLevel <int>
    Heading level to split on (1 = H1, 2 = H2, etc.)
    Default: 1 (splits on H1/# headings)

-OutputFolder <string>
    Custom output folder path (optional)
    Default: Creates folder with same name as markdown file

-IncludePageNumbers <switch>
    Preserve "## Page X" markers from PDF extractions
    Default: false (removes page markers)

-CreateIndex <switch>
    Create _index.md with navigation links
    Default: true

Output Structure

Example output structure:

source-document\
├── _index.md                    # Navigation index
├── 00-front-matter.md          # Preface, TOC, etc.
├── 01-introduction.md          # Chapter 1
├── 02-getting-started.md       # Chapter 2
├── 03-advanced-topics.md       # Chapter 3
└── ...

Each file contains:

• Original heading as title
• Full section content
• Preserved formatting (code blocks, lists, tables)
• Optional: Back/Next navigation links

Advanced Features

Smart Filename Generation

The script automatically:

• Removes special characters from filenames
• Limits filename length to 50 characters
• Adds sequential numbers for ordering
• Handles duplicate section names

Content Preservation

Maintains:

• Code blocks with syntax highlighting
• Nested lists and tables
• Inline formatting (bold, italic, links)
• Images and media references
• Horizontal rules and separators

Table of Contents Detection

Recognizes various TOC formats:

• "Table of Contents"
• "Contents"
• "TOC"
• Markdown link lists
• Numbered chapter lists

Typical Use Cases

1. Split extracted PDF books into chapters for easier navigation
2. Organize large documentation files into topic-specific files
3. Create modular content from monolithic markdown files
4. Prepare documentation for static site generators (Jekyll, Hugo, etc.)
5. Split meeting notes or journals by date/section

Tips & Best Practices

• Consistent heading structure: Ensure your markdown uses consistent heading levels
• Unique section names: Avoid duplicate chapter/section titles when possible
• Backup originals: Keep the original file before splitting
• Review output: Check the first few split files to ensure structure is preserved
• Adjust split level: If output has too many/few files, try different SplitLevel values

Error Handling

The script handles:

• Missing or invalid markdown files
• Insufficient permissions for folder creation
• Malformed markdown structure
• Empty sections or content
• Special characters in headings

Performance

• Processes typical books (500+ pages) in seconds
• Memory-efficient streaming for large files
• Minimal CPU usage during parsing
• Suitable for batch processing multiple files

Integration with Other Skills

Common workflow:

1. Use pdf-text-extractor to convert PDF → markdown
2. Use md-splitter to split into chapters
3. Result: Organized chapter-based documentation

Example combined usage:

# Step 1: Extract PDF
.\.github\skills\pdf-text-extractor\scripts\Extract-PDF-Text.ps1 `
    -PDFPath ".\docs\manual.pdf"

# Step 2: Split into chapters
.\.github\skills\md-splitter\scripts\Split-Markdown.ps1 `
    -MarkdownPath ".\docs\manual.md"

Troubleshooting

Issue: Too many small files created

• Solution: Increase -SplitLevel to split on deeper headings (2 or 3)

Issue: Content appears in wrong files

• Solution: Check markdown heading consistency; ensure proper hierarchy

Issue: Special characters in filenames

• Solution: Script auto-sanitizes; check -OutputFolder parameter for custom path

Issue: Missing content in split files

• Solution: Verify source markdown structure; check for unclosed code blocks

Learning More

• Study the generated _index.md for navigation patterns
• Examine split files to understand content distribution
• Experiment with different SplitLevel values
• Combine with other markdown processing tools

Summary

The Markdown Splitter skill transforms large, monolithic markdown documents into organized, navigable collections of smaller files. Perfect for managing documentation, books, and large reference materials extracted from PDFs or other sources.