How to split a long markdown file into chapter files by heading
- Step 1Open the Markdown Splitter and drop your manuscript — Drag your single long-form
.md,.mdx, or.markdownfile onto the tool. It accepts one file at a time (this is a one-to-many tool, not a batch tool). Splitting is Pro-only — on the Free tier the run is blocked withmd-splitter requires a Pro subscription. - Step 2Choose the split heading level — Use the Split at heading level dropdown to pick
H1,H2, orH3. Pick the level that marks your chapter boundaries. If your chapters are## Chapter N, chooseH2. Default isH1. There are no other options — no custom filename pattern, no per-file frontmatter toggle. - Step 3Check your headings are real ATX headings — The tool matches ATX headings (
#,##,###) at the start of a line. Setext underline headings (Titlefollowed by===or---) are not detected as split points. If your manuscript uses underline-style headings, convert them to#-style first, or you will get a single-chapter (or empty) result. - Step 4Run the split — Click run. The tool slices the body at every heading of your chosen level or shallower, builds one in-memory
.mdper section, and zips them with JSZip. If no heading at the chosen level exists, it stops withNo H{level} headings found to split on.— change the level or fix the headings. - Step 5Download the ZIP — Click Download .zip. You get
<input-name>-chapters.zipcontaining00-...md,01-...md, and so on. The preview panel confirms the file is ready; the actual chapter contents live inside the archive. - Step 6Extract and verify chapter order — Unzip into a folder or repo. The
NN-prefixes sort chapters in document order. Open the first file to confirm your frontmatter came across, and skim for any preamble that lived before your first heading — that text is intentionally not emitted as a chapter and may need to be re-added manually.
What each split level does to a manuscript
The dropdown offers exactly three values. A heading shallower than your chosen level also ends the current chapter, because the splitter breaks on any heading of level less-than-or-equal to your selection.
| Split level (dropdown) | splitLevel value | Breaks on | Typical manuscript structure | Result |
|---|---|---|---|---|
| H1 | 1 (default) | Every # heading only | # Chapter One, # Chapter Two as top-level dividers | One file per # section; deeper ##/### stay inside their chapter file |
| H2 | 2 | Every # and ## heading | # Part I parts containing ## Chapter chapters | One file per ## section; each # part divider also starts a new file |
| H3 | 3 | Every #, ##, and ### heading | ### Section granularity inside chapters | Most files, finest granularity; every #/##/### starts a new file |
Output filename and content rules
Filenames are generated from heading text by GitHub's slug algorithm; there is no UI to change the pattern. Behaviour is fixed in the splitter implementation.
| Aspect | Behaviour | Example |
|---|---|---|
| Filename pattern | NN-slug.md, two-digit zero-padded index from 00 | First chapter # Prologue becomes 00-prologue.md |
| Slug rules | Lowercase, strip characters other than word/space/hyphen, spaces to hyphens, collapse repeats | # The End?! becomes 00-the-end.md |
| Emphasis in headings | *, _, and backticks are stripped from the title before slugging | # **Bold** Title becomes 00-bold-title.md |
| Text before first heading | Discarded — not written to any chapter file | A paragraph above # Chapter One is lost |
| Frontmatter | YAML (---) or TOML (+++) block is prepended to the first chapter only | Title block lands in 00-*.md, not in later files |
| ZIP name | Input name with .md/.mdx/.markdown replaced by -chapters.zip | novel.md becomes novel-chapters.zip |
Tier limits for the Markdown family
The splitter is Pro-only. The character limit (charLimit) is separate from the byte size limit — a long manuscript can hit the char cap before the MB cap.
| Tier | Max file size | Max characters | Can run md-splitter? |
|---|---|---|---|
| Free | 1 MB | 500,000 | No — blocked, Pro required |
| Pro | 10 MB | 5,000,000 | Yes |
| Pro-media | 50 MB | 20,000,000 | Yes |
| Developer | 500 MB | Unlimited | Yes |
Cookbook
Concrete before/after structures showing what the ZIP contains for common manuscript shapes. Headings are real ATX headings; everything runs in the browser.
Chapter book split on H1
A novel where each chapter is a top-level # heading. Split level H1 produces one file per chapter, in order.
Input manuscript.md: # Chapter One The rain had not stopped... # Chapter Two Morning came grey and slow... # Chapter Three She never wrote back... Split level: H1 Output manuscript-chapters.zip: 00-chapter-one.md 01-chapter-two.md 02-chapter-three.md
Parts and chapters split on H2
A book organised as # parts containing ## chapters. Splitting on H2 breaks at every chapter AND at every part divider, because the splitter breaks on any heading at or above the chosen level.
Input book.md: # Part I ## The Arrival ... ## The Letter ... # Part II ## The Return ... Split level: H2 Output book-chapters.zip: 00-part-i.md (just the # Part I divider + any text under it) 01-the-arrival.md 02-the-letter.md 03-part-ii.md 04-the-return.md
Frontmatter lands in the first chapter only
A manuscript with a YAML title block. The block is copied into the first output file and is not repeated in later chapters.
Input draft.md: --- title: The Long Goodbye author: J. Marlowe --- # Chapter One ... # Chapter Two ... Split level: H1 Output: 00-chapter-one.md -> starts with the --- title block, then # Chapter One 01-chapter-two.md -> no frontmatter, just # Chapter Two
Preamble before the first heading is dropped
Any prose that appears before your first split-level heading is not emitted. If you need it, move it under a heading first.
Input story.md: A quick note to the reader before we begin. # Chapter One ... Split level: H1 Output: 00-chapter-one.md (the reader note is GONE) Fix: wrap the note under a heading so it survives: # Author's Note A quick note to the reader before we begin. # Chapter One ...
Code-fence headings are not split points
A # line inside a fenced code block is shell/comment syntax, not a Markdown heading. The splitter ignores it, so your tutorial chapter stays whole.
Input guide.md: # Setup Run the installer: ```bash # this is a shell comment, not a heading brew install foo ``` # Usage ... Split level: H1 Output: 00-setup.md (includes the whole bash block, comment intact) 01-usage.md
Edge cases and what actually happens
Run attempted on the Free tier
Pro requiredThe splitter is a Pro feature. On Free, the run throws md-splitter requires a Pro subscription. — ZIP/multi-file output is gated. Upgrade to Pro (10 MB / 5,000,000 chars) or higher to use it.
No heading exists at the chosen level
errorIf you pick H2 but the document has only # headings, the splitter finds nothing to split on and stops with No H{level} headings found to split on. Lower the split level (H2 also breaks on H1) or fix your heading levels.
Setext (underline) headings
Not detectedOnly ATX headings (#, ##, ###) are matched. A title underlined with === or --- is not treated as a split point. Convert underline headings to #-style before splitting, or the whole document collapses into one chapter.
Text before the first heading
Dropped by designThe splitter only starts emitting once it hits the first split-level heading. Any preamble above that heading is discarded. Wrap it under its own heading (e.g. # Preface) if you need it preserved as a chapter file.
Two chapters share the same heading text
PreservedBoth files are written; the NN- index keeps them distinct on disk even though the slug part is identical (00-introduction.md, 01-introduction.md). Nothing is overwritten because the index prefix differs.
Heading with only punctuation or emoji
PreservedThe slug strips everything except word characters, spaces, and hyphens. A heading like # ??? slugs to an empty string, producing a filename such as 00-.md. Rename after extraction if you need a meaningful name.
Frontmatter but no headings at all
errorFrontmatter alone does not create a chapter. With a frontmatter block and no ATX heading at the chosen level, the splitter reports no headings found and produces no ZIP. Add at least one heading.
Internal links between chapters
May breakSame-document anchor links (e.g. [see Chapter 3](#chapter-three)) no longer resolve once chapters are separate files. After splitting, rewrite them as relative file links (02-chapter-three.md). The splitter does not rewrite links.
Manuscript exceeds the character limit
errorFiles are read with the tier char limit enforced. A Pro manuscript over 5,000,000 characters is rejected with a message naming the count and the limit. Use a higher tier (Pro-media 20M, Developer unlimited) for very large books.
Recombining chapters later
SupportedTo reassemble the chapter files into one document, use md-merger. It joins multiple files (Pro: up to the batch limit) with --- separators and an optional generated table of contents.
Frequently asked questions
What heading levels can I split on?
Exactly three: H1, H2, or H3, chosen from the Split at heading level dropdown. Default is H1. There is no H4+ option. A heading shallower than your choice also ends the current chapter — splitting on H2 will break on # part dividers too.
How are the output filenames named?
Each file is NN-slug.md. NN is a two-digit, zero-padded index starting at 00 to preserve document order. The slug is GitHub-style: the heading text lowercased, with *, _, and backticks removed, then everything except word characters, spaces, and hyphens stripped, spaces turned into hyphens. So ## Getting Started! becomes 01-getting-started.md.
Can I choose my own filename pattern?
No. The filename scheme is fixed at NN-slug.md and the only control in the tool is the heading level. If you need different names, rename the files after you extract the ZIP.
What format is the output?
A single ZIP archive containing one .md file per section. The ZIP is named after your input file with the extension swapped for -chapters.zip (so book.md produces book-chapters.zip). It is built in your browser with JSZip.
What happens to text before my first heading?
It is dropped. The splitter does not start a chapter until it reaches the first heading at your chosen level, so any preamble above that point is not written to any file. Put it under a heading (e.g. # Preface) if you want it preserved.
Is my frontmatter kept?
Yes, but only in the first chapter. A YAML (---) or TOML (+++) block at the very top of the document is detected and prepended to the first output file. It is not copied into the later chapter files — add per-chapter frontmatter manually if you need it.
Does it detect headings inside code blocks?
No, and that is deliberate. The splitter tracks fenced code blocks (lines starting with ``) and ignores # lines inside them, so a shell comment like # install` in a code sample never starts a new chapter.
Why do I get an error saying no headings were found?
You picked a split level that does not exist in the document — for example H2 when every heading is #. The message is No H{level} headings found to split on. Lower the split level or correct your heading levels. Note that underline-style (Setext) headings are not detected; convert them to #-style.
Will internal cross-references survive the split?
Same-document anchor links break, because each chapter is now its own file. The splitter does not rewrite links. After extracting, change [link](#some-heading) references to relative file paths like [link](03-some-heading.md).
Can I split more than one file at once?
No. This is a one-to-many tool — it takes a single Markdown file and produces many files. It does not accept multiple inputs. To combine many files into one, use the Markdown Merger instead.
How large a manuscript can I split?
It depends on tier. Pro allows up to 10 MB / 5,000,000 characters, Pro-media up to 50 MB / 20,000,000 characters, and Developer up to 500 MB with no character cap. The character limit is enforced separately from the byte size, so a dense text file can hit the char cap first.
How do I put the chapters back together?
Use the Markdown Merger, which joins files with --- separators and an optional table of contents. To re-level headings after a split (for example to demote chapters into sections), use the Heading Shifter. To rebuild a master TOC, see the TOC Generator.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.