How to split a single-file handbook into per-section markdown files
- Step 1Drop the single-file handbook — Upload your one
handbook.md. The splitter takes one file and returns many. It is Pro-only — Free blocks the run withmd-splitter requires a Pro subscription. - Step 2Set the split level to your section level — Use Split at heading level. If sections are
##headings under a single# Handbooktitle, chooseH2. Note thatH2will also break at the# Handbooktitle, giving you a small lead file. - Step 3Verify your sections are ATX headings — Only
#/##/###headings are detected. If your handbook uses underline-style (Setext) section titles, convert them to#-style first or the document will not split. - Step 4Run the split — Run the tool. It cuts at each section heading and zips one
.mdper section with JSZip. If the chosen level has no headings, it stops withNo H{level} headings found to split on. - Step 5Download and lay out the repo — Download
<handbook>-chapters.zipand extract into asections/directory. TheNN-prefixes keep section order for your concatenation build step. - Step 6Assign ownership and re-link — Map each section file to its team in CODEOWNERS. Convert any in-handbook anchor links to relative file links, and re-add any preamble that lived above the first section heading — it is not in the ZIP.
Split level by handbook structure
Pick the level your sections use. The splitter breaks on any heading at or shallower than your choice, so the top title can become its own thin file.
| Handbook structure | Section marker | Set split level to | Result |
|---|---|---|---|
| Single title, top-level sections | # Onboarding, # Security | H1 | One file per section |
One # Handbook title, ## sections | ## On-Call, ## Incidents | H2 | One file per section plus a thin 00-handbook.md lead file |
| Sections with sub-sections to split out | ### Runbook: DB Failover | H3 | Finest split; every #/##/### becomes a file |
Filename and content rules (fixed)
No filename-pattern option exists; behaviour below is built into the tool.
| Aspect | Rule | Ops note |
|---|---|---|
| Filename | NN-slug.md, zero-padded from 00 | Order preserved for concat builds |
| Slug | Section title, GitHub slug algorithm | ## On-Call! -> 02-on-call.md |
| Frontmatter | Prepended to first section only | Handbook-wide metadata lands in 00-*.md |
| Preamble before first heading | Dropped | Wrap intro text in a heading to keep it |
| Code-fence headings | Ignored | # kubectl comments stay inside the runbook |
| ZIP name | <input>-chapters.zip | handbook.md -> handbook-chapters.zip |
Tier limits (Markdown family)
Pro-only tool. Character limit is separate from byte size.
| Tier | Max file size | Max characters | md-splitter |
|---|---|---|---|
| Free | 1 MB | 500,000 | Blocked (Pro required) |
| Pro | 10 MB | 5,000,000 | Available |
| Pro-media | 50 MB | 20,000,000 | Available |
| Developer | 500 MB | Unlimited | Available |
Cookbook
Handbook structures and the exact section files they produce. Processing is in-browser; internal content stays local.
Top-level sections on H1
A handbook where each section is a # heading. Split on H1 for one file per section.
Input handbook.md: # Onboarding ... # Security Policy ... # On-Call Rotation ... Split level: H1 Output handbook-chapters.zip: 00-onboarding.md 01-security-policy.md 02-on-call-rotation.md
Titled handbook with H2 sections
A single # Engineering Handbook title wrapping ## sections. Splitting on H2 also cuts at the title, producing a thin lead file.
Input handbook.md: # Engineering Handbook Welcome to the team. ## Onboarding ... ## Incident Response ... Split level: H2 Output: 00-engineering-handbook.md (title + 'Welcome to the team.') 01-onboarding.md 02-incident-response.md
Runbook with shell comments stays whole
An on-call section full of # shell comments inside code fences is not fractured, because code-fence headings are ignored.
Input handbook.md: # On-Call Restart the service: ```bash # scale down kubectl scale deploy/api --replicas=0 # scale up kubectl scale deploy/api --replicas=3 ``` # Postmortems ... Split level: H1 Output: 00-on-call.md (full bash block intact) 01-postmortems.md
Intro paragraph above the first section is dropped
Lead text above the first heading is not emitted. Wrap it in a heading to keep it.
Input handbook.md: This handbook is maintained by all teams. # Onboarding ... Split level: H1 Output: 00-onboarding.md (the maintenance note is GONE) Fix: # About This Handbook This handbook is maintained by all teams. # Onboarding ...
Build-time reassembly
Per-team section files are recombined into the published handbook with the Markdown Merger as a build step.
Repo layout: sections/00-about.md (owner: platform) sections/01-onboarding.md (owner: people-ops) sections/02-security.md (owner: security) Build step: md-merger: drop sections/*.md -> handbook.md (md-merger joins with --- and an optional TOC at the top)
Edge cases and what actually happens
Free tier
Pro requiredThe splitter is Pro-only. Free users see md-splitter requires a Pro subscription. Upgrade to Pro or higher to extract sections.
Chosen level has no headings
errorIf you split on H2 but every heading is #, you get No H{level} headings found to split on. Lower the level — H2 also breaks on # — or fix the heading levels.
Title heading becomes a thin lead file
ExpectedSplitting on H2 when there is a single # Handbook title produces 00-<title>.md containing just the title and any intro text under it. This is correct behaviour, not a bug — delete or keep the lead file as you prefer.
Setext underline section titles
Not detectedUnderline-style section headings are not recognised. Convert them to #-style first or the handbook will not split.
Text before the first section
Dropped by designA maintenance note or banner above the first heading is not written to any file. Wrap it in its own heading to preserve it as a section file.
Two sections share a title
PreservedTwo ## FAQ sections produce 00-faq.md and 01-faq.md; the index prefix keeps them distinct. Nothing is overwritten.
Cross-section links
May breakAnchor links such as [see Security](#security-policy) stop resolving once sections are separate files. Rewrite them as relative file links (02-security-policy.md). The splitter does not adjust links — use md-link-validator afterward to find broken ones.
Headings need re-leveling after extraction
SupportedIf you want each extracted section to start at # instead of ##, run md-heading-shifter on the files to promote their headings up a level.
Handbook over the char limit
errorThe read enforces the tier char limit; a Pro handbook over 5,000,000 characters is rejected with the count named. Use Pro-media (20M) or Developer (unlimited) for very large handbooks.
Section files contain secrets
ReviewThe splitter copies content verbatim — if a runbook section has hardcoded tokens, they end up in the section file. Run md-secret-redactor on the files before committing them to a shared repo.
Frequently asked questions
What split level should I use for a handbook?
Match it to your section headings. A handbook with a single # Handbook title and ## Section headings should split on H2. Note that H2 also breaks at the # Handbook title, so you get a small lead file (00-handbook.md) in addition to the section files.
How do I rebuild the full handbook from the section files?
Use the Markdown Merger as a build step. It concatenates the section files with --- separators and can prepend a generated table of contents. Wire it into CI so the published handbook is always assembled from the owned section files.
Can multiple sections share an owner?
Yes — that is a repo-organisation choice, not a tool feature. Group section files into team folders or map them to owners in CODEOWNERS. The splitter just produces ordered NN-slug.md files; how you assign them is up to you.
Will internal cross-references survive?
Same-handbook anchor links break once sections are separate files. The splitter does not rewrite links. After extraction, change [link](#section) to relative paths and run md-link-validator to catch any that still point nowhere.
What about the intro paragraph at the top of the handbook?
Text above the first heading is dropped. Wrap it under its own heading (# About This Handbook) so it becomes the first section file instead of being lost.
Are the filenames customisable?
No. They are fixed at NN-slug.md, where the slug comes from the section title. The only control is the heading level. Rename after extracting if you need a different convention.
Does it keep section order?
Yes. The NN- prefix is assigned in document order, so files sort correctly and a *.md concatenation build reproduces the original section order.
What output do I get?
A ZIP of .md files named <handbook>-chapters.zip, one file per section, generated in the browser with JSZip. The handbook content is never uploaded.
Does it handle code blocks safely?
Yes. Headings inside fenced code blocks are ignored, so a runbook section with # shell-comment lines inside ``` fences is not split into stray files.
Is there a size limit?
By tier: Pro 10 MB / 5,000,000 characters, Pro-media 50 MB / 20,000,000, Developer 500 MB / unlimited. The character count is checked separately from byte size.
Can I split several handbooks at once?
No. It processes one file at a time. To combine many files into one, use the Markdown Merger.
How do I make sure section files have no leaked secrets before committing?
Run md-secret-redactor on the extracted files. The splitter copies content verbatim, so any tokens or keys in a runbook section carry into the section file unchanged.
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.