md-heading-splitter

A TypeScript CLI that splits a Markdown file into one file per top-level (# ) heading.

Install

From npm (recommended)

npm install -g md-heading-splitter

This puts md-heading-splitter on your PATH.

From source

npm install
npm run build

This compiles src/ to dist/ and marks dist/cli.js executable. To use the command as md-heading-splitter on your PATH, link it globally:

npm link

Usage

md-heading-splitter <input file.md> <output folder>

Or, without linking:

node dist/cli.js <input file.md> <output folder>

The output folder is created (including any missing parent directories) if it doesn't already exist.

Example

Given notes.md:

# Getting Started

Install the thing.

# Configuration

Set the flags.

Running:

md-heading-splitter notes.md out/

produces:

out/
├── Getting Started.md
├── Configuration.md
└── index.md

index.md lists the headings in their original order, linking to each file:

- [Getting Started](./Getting Started.md)
- [Configuration](./Configuration.md)

Any text before the first # heading (a preamble) is carried into index.md above the heading list. Content between an # H1 and the next # H1 — including any ##/### subheadings — stays with that section.

Filename handling

• Filenames are derived from the heading text, with characters illegal on common filesystems (< > : " / \ | ? *) replaced.
• The target filesystem is assumed case-insensitive. If two headings would produce the same filename (e.g. Foo Bar and foo bar), later ones are suffixed (foo bar-2.md, foo bar-3.md, ...) to avoid collisions.
• The generated index file is normally named index.md. If the source document has an actual heading that also maps to index.md (case-insensitively), the generated index yields and is renamed _index.md instead (adding further underscores if still in conflict), leaving the real heading's file as index.md.

Development

npm run build   # compile TypeScript to dist/
npm start        # run the compiled CLI (node dist/cli.js)

License

MIT — see LICENSE.