How to pro markdown chapter splitter
- Step 1Confirm you are on Pro or higher — The splitter is Pro-only. On Free, the run stops with
md-splitter requires a Pro subscription.Pro, Pro-media, and Developer all have access; the difference between them is the size limit, not the feature set. - Step 2Drop one Markdown file — Upload a single
.md,.mdx, or.markdownfile. The splitter is one-to-many; it does not accept multiple inputs. The companion many-to-one tool is the Markdown Merger. - Step 3Pick the split level — Set Split at heading level to
H1,H2, orH3(defaultH1). The tool starts a new file at every heading of that level or shallower. There are no other options to configure. - Step 4Run and watch for the empty-result error — Run the split. If your chosen level has no matching headings, the tool stops with
No H{level} headings found to split on.— lower the level or fix the headings. - Step 5Download the ZIP — Click Download .zip to save
<input>-chapters.zip. It contains one.mdper section, namedNN-slug.mdin document order. - Step 6Round-trip with the Merger if needed — After editing the per-file pieces, recombine them with the Pro Markdown Merger, which joins files with
---separators and an optional table of contents.
Free vs Pro for the splitter
The splitter is gated. Free cannot run it at all; the value of Pro is access plus larger inputs.
| Capability | Free | Pro and above |
|---|---|---|
| Run md-splitter | Blocked (md-splitter requires a Pro subscription.) | Available |
| Output | n/a | ZIP of NN-slug.md files |
| Max file size | 1 MB | 10 MB (Pro) up to 500 MB (Developer) |
| Max characters | 500,000 | 5,000,000 (Pro) up to unlimited (Developer) |
| Companion Markdown Merger | Single file only | Multi-file merge (Pro) |
What the single control does
The only configurable option. The splitter breaks on any heading at or shallower than the chosen level.
| Split at heading level | splitLevel | Breaks on | Granularity |
|---|---|---|---|
| H1 | 1 (default) | # only | Coarsest — one file per top-level section |
| H2 | 2 | # and ## | Medium — # dividers also start files |
| H3 | 3 | #, ##, ### | Finest — most files |
Fixed splitter behaviour
These behaviours are built in and not configurable.
| Behaviour | Detail |
|---|---|
| Filename | NN-slug.md, zero-padded index from 00, GitHub-style slug of the heading |
| Frontmatter | YAML/TOML block prepended to the first file only |
| Pre-first-heading text | Dropped |
| Code-fence headings | Ignored |
| ZIP name | <input>-chapters.zip |
| API availability | Browser-only — not exposed via the JAD API |
Cookbook
Pro-workflow recipes showing the real behaviour and the round trip with the Merger. Everything runs in the browser.
Basic H1 split
The default workflow: one document, split at top-level headings.
Input doc.md: # Overview ... # Setup ... # Reference ... Split level: H1 Output doc-chapters.zip: 00-overview.md 01-setup.md 02-reference.md
Free tier hits the gate
On Free, the run is blocked before any output is produced.
Tier: Free Action: run md-splitter on doc.md Result: Error: md-splitter requires a Pro subscription. -> Upgrade to Pro (10 MB / 5,000,000 chars) to run it.
No matching headings
Choosing a level with no headings stops the run with a clear error.
Input notes.md: # Notes Just one heading, lots of text. Split level: H2 Result: Error: No H2 headings found to split on. -> Switch to H1 (which matches the # Notes heading).
Frontmatter goes to the first file only
A metadata block is carried into the first file and not repeated.
Input doc.md: --- title: Release Notes --- # v2.0 ... # v1.9 ... Split level: H1 Output: 00-v2-0.md -> begins with the --- title block 01-v1-9.md -> no frontmatter
Split then merge round trip
The Pro split-edit-merge loop using the companion Merger.
1. md-splitter: doc.md -> 00..NN.md (edit the pieces)
2. md-merger: drop the edited files -> merged.md
md-merger options:
- Generate Table of Contents (default on)
- Use filename as H1 when a file has none (default on)
Files are joined with --- separators.Edge cases and what actually happens
Run on Free tier
Pro requiredThe splitter is gated. Free users get md-splitter requires a Pro subscription. with no output. Upgrade to Pro or higher; the feature is identical across Pro/Pro-media/Developer apart from size limits.
No heading at the chosen level
errorIf the document has no heading at the selected level, the run stops with No H{level} headings found to split on. Lower the level (a lower level also matches higher headings) or correct the heading levels.
Expecting an API endpoint
Not availableUnlike the text-transform Markdown tools, md-splitter is browser-only — it is not exposed through the JAD API (binary ZIP output is not returned server-side). Use the web tool for splitting; there is no headless/automated split endpoint.
Text before the first heading
Dropped by designPreamble above the first split-level heading is not written to any file. Wrap it under a heading to preserve it as a file.
Frontmatter only in the first file
ExpectedThe YAML/TOML block is prepended to the first output file only, not repeated across files. Add per-file metadata manually if you need it everywhere.
Multiple files dropped
Single file onlyThe splitter accepts one input file. It does not batch-split. For combining many files into one, use the Markdown Merger, which is the many-to-one counterpart.
Setext underline headings
Not detectedOnly ATX (#-style) headings are split points. Underline-style headings are ignored. Convert them first or the document will not split.
Duplicate heading text
PreservedTwo files with the same slug are kept distinct by the NN- index prefix (00-intro.md, 01-intro.md). Nothing is overwritten.
Input over the tier char limit
errorThe file read enforces the character limit for your tier; an over-limit file is rejected with a message naming the count and limit. Move to a higher tier (Pro-media 20M, Developer unlimited) for very large documents.
Heading inside a code block
IgnoredA # line inside a fenced code block is not a split point. This is correct behaviour — your code samples stay inside the right file.
Frequently asked questions
Why is the splitter a Pro feature?
It produces multi-file ZIP output, which is gated above Free. On Free the run is blocked with md-splitter requires a Pro subscription.; single-file Markdown transforms (linting, prettifying, TOC generation, conversions) remain free. Pro, Pro-media, and Developer all include the splitter.
What exactly does Pro unlock for splitting?
Two things: access to the tool at all (it is blocked on Free), and larger inputs — Pro allows 10 MB / 5,000,000 characters, Pro-media 50 MB / 20,000,000, Developer 500 MB / unlimited. The split logic and the single heading-level control are the same across all paid tiers.
What does the output look like?
A ZIP named <input>-chapters.zip containing one .md per section, each named NN-slug.md — a two-digit order index plus a GitHub-style slug of the heading text. The ZIP is built in your browser with JSZip.
Is there an API for automated splitting?
No. md-splitter is browser-only; it is not exposed through the JAD API because it returns binary ZIP output. The text-transform Markdown tools have an API, but for splitting you use the web tool. There is no headless split endpoint.
What options can I configure?
Exactly one: Split at heading level (H1, H2, or H3, default H1). There is no filename-pattern picker, no per-file frontmatter toggle, and no reorder step. The behaviour is otherwise fixed.
What does each split level do?
H1 breaks only on # headings (coarsest). H2 breaks on # and ##. H3 breaks on #, ##, and ### (finest). The splitter starts a new file at any heading at or shallower than your chosen level, so a lower level always also catches the higher headings.
What happens to text before the first heading?
It is dropped. The splitter does not start a file until the first heading at the chosen level. Wrap any preamble under a heading to keep it as a file.
Is my frontmatter preserved?
Yes, but only in the first file. A YAML (---) or TOML (+++) block at the top is prepended to the first output file and not repeated. Add metadata to later files manually if you need it.
Can I split multiple files at once?
No — it takes one file and produces many. The many-to-one counterpart is the Markdown Merger, which also requires Pro for multi-file merges.
What if I get 'No headings found to split on'?
You selected a level with no matching headings (e.g. H2 on a #-only document), or your headings are underline-style (Setext), which the splitter does not detect. Lower the split level or convert headings to #-style.
Will my generated content persist if I don't keep Pro?
Any ZIP you downloaded is yours to keep — it is saved to your machine. Pro access controls whether you can run the tool, not whether downloaded files survive. Splitting runs locally in your browser, so nothing is stored on JAD's servers either way.
Which related Pro tools should I know about?
The Markdown Merger for the split-edit-merge round trip; the TOC Generator to rebuild a table of contents; and the Heading Shifter to re-level headings in the split files.
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.