mdstruct

Working with large markdown files is awkward. You can’t easily grep for a section, version control changes are noisy, and reorganising content means careful copy-paste surgery.

mdstruct treats your markdown like a filesystem. Split a document by its headings into a directory tree, edit the pieces with your usual tools, then join them back together.

# Split a markdown file into directories
mdstruct split notes.md

# Edit sections as separate files
vim notes/introduction/README.md

# Rejoin into a single file
mdstruct join notes

The gron philosophy

gron transforms JSON into discrete assignments you can grep. mdstruct does the same for markdown: it turns a monolithic document into a greppable directory structure.

example/
├── first-section/
│   ├── README.md
│   ├── subsection-a.md
│   └── subsection-b.md

Each section becomes a file. Each heading level becomes a directory. Standard unix tools work as expected.

Fractional indexing

When sections aren’t alphabetically ordered, mdstruct adds alphanumeric prefixes to preserve order. The clever bit: you can insert new sections between existing ones using fractional indices.

# Original structure after split
0.intro/
1.main-content/
2.conclusion/

# Insert a new section between intro and main-content
mkdir 0m.background/

# Join preserves the order
mdstruct join doc

The 0m prefix sorts after 0 but before 1. You can nest deeper (0mm, 0mmm) for tighter spaces. When the prefixes get messy, a round-trip split-join rebalances everything.

Installation

pip install mdstruct