markitect-main/docs/md-explode-command.md

MD-Explode Command Documentation

Overview

The md-explode command transforms a single markdown file with hierarchical structure into an organized directory tree, where each heading becomes a separate file or directory. This is particularly useful for managing large documents like books, technical documentation, or structured reports.

Installation

The md-explode command is built into MarkiTect as part of the markdown commands plugin. No additional installation is required.

Usage

Basic Syntax

markitect md-explode <input_file> [OPTIONS]

Parameters

Required

• INPUT_FILE - Path to the markdown file to explode

Options

• --output-dir, -o PATH - Output directory for exploded files (default: <filename>_exploded/)
• --max-depth INTEGER - Maximum directory nesting depth (default: 10)
• --dry-run - Preview what would be created without actually creating files
• --verbose, -v - Show detailed output during processing

Examples

Basic Usage

# Explode book.md into book_exploded/ directory
markitect md-explode book.md

Custom Output Directory

# Explode into a specific directory
markitect md-explode documentation.md --output-dir ./chapters/

Preview Mode

# See what structure would be created without creating files
markitect md-explode large-document.md --dry-run --verbose

Verbose Output

# Get detailed information about the explosion process
markitect md-explode technical-guide.md --verbose

Input Format

The command expects markdown files with hierarchical heading structure:

# Part 1: Introduction
Introduction content here.

## Chapter 1: Getting Started
Chapter content here.

### Section 1.1: Installation
Installation instructions.

### Section 1.2: Configuration
Configuration details.

## Chapter 2: Advanced Topics
Advanced content.

# Part 2: Reference
Reference material.

Output Structure

The command creates a directory structure that mirrors the document hierarchy:

document_exploded/
├── part_1_introduction/
│   ├── index.md                    # Part introduction content
│   ├── chapter_1_getting_started/
│   │   ├── index.md                # Chapter content
│   │   ├── section_11_installation.md
│   │   └── section_12_configuration.md
│   └── chapter_2_advanced_topics.md
└── part_2_reference.md

Structure Rules

1. Directories are created for headings that have child sections
2. Files are created for leaf sections (no children)
3. Index files contain the content of parent sections
4. Nested structure preserves the document hierarchy
5. Safe filenames are generated from heading text

Filename Generation

Headings are converted to filesystem-safe filenames using these rules:

• Lowercase conversion: "Chapter 1" → "chapter_1"
• Special character removal: "What's New?" → "whats_new"
• Unicode normalization: "Café & Résumé" → "cafe_resume"
• Number preservation: "Section 1.1.1" → "section_1_1_1"
• Path character handling: "File/Path Issues" → "file_path_issues"
• Length limiting: Very long titles are truncated to 100 characters
• Conflict resolution: Duplicate names get numbered suffixes

Features

Front Matter Support

YAML front matter is automatically detected and handled:

---
title: "My Document"
author: "John Doe"
---

# Chapter 1
Content starts here...

Front matter is preserved appropriately during the explosion process.

Content Preservation

• Markdown formatting is fully preserved in exploded files
• Code blocks maintain their syntax highlighting
• Tables, lists, and links are kept intact
• Images and media references are preserved

Error Handling

• Missing files: Clear error messages for non-existent input files
• Permission errors: Graceful handling of filesystem permission issues
• Malformed markdown: Robust parsing that handles inconsistent heading levels
• Empty files: Appropriate handling of files with no heading structure

Advanced Usage

Limiting Directory Depth

# Limit to 3 levels of nesting
markitect md-explode complex-doc.md --max-depth 3

When depth is exceeded, deeper sections are flattened into files rather than creating more directories.

Working with Large Documents

For very large documents, use dry-run mode first to preview the structure:

markitect md-explode huge-manual.md --dry-run --verbose

This helps you understand the output structure and estimate disk space requirements.

Troubleshooting

Common Issues

"No heading structure found"

• The markdown file contains no headings (#, ##, etc.)
• Solution: Add headings to structure your document

"Permission denied"

• Insufficient permissions to write to the output directory
• Solution: Check directory permissions or specify a different output location

"File already exists"

• The output directory already exists and contains files
• Solution: Choose a different output directory or remove existing files

"Invalid markdown format"

• The input file is not valid markdown
• Solution: Check the file format and fix any syntax errors

Getting Help

# Show command help
markitect md-explode --help

# Show general MarkiTect help
markitect --help

Best Practices

1. Use descriptive headings - They become directory and file names
2. Maintain consistent heading levels - Don't skip from # to ###
3. Keep headings concise - Very long headings result in long filenames
4. Avoid special characters in headings when possible
5. Preview first - Use --dry-run for large documents
6. Backup originals - Always keep a copy of your source markdown file

Integration

The md-explode command works well with other MarkiTect commands:

# Render exploded files to HTML
markitect md-render exploded_directory/ --recursive

# Create an index of the exploded structure
markitect md-index exploded_directory/ --recursive

This creates a complete documentation workflow from single file to organized, rendered website.

Technical Details

Implementation

• Language: Python 3.8+
• Dependencies: Click for CLI, unicodedata for filename normalization
• Parser: Custom markdown heading parser (no external markdown library required)
• Performance: Efficient for documents up to thousands of sections

File System Compatibility

• Cross-platform: Works on Windows, macOS, and Linux
• Character encoding: UTF-8 throughout
• Filename limits: Respects filesystem limitations
• Path length: Handles deep directory structures appropriately

See Also

• md-render - Render markdown files to HTML
• md-index - Generate index pages for directories
• md-ingest - Import and process markdown files

---

This documentation is for MarkiTect version 1.0+