How to merge handbook sections into one
- Step 1Collect the current section files — Pull the latest version of each handbook section from your repo or shared drive. The merger reads files locally and accepts
.md,.mdx,.markdown, and.txt, so a mix of formats from different teams is fine. - Step 2Use Upload mode, not Paste — Switch to the Upload file tab. Paste mode handles a single document only; an assembled handbook needs all the section files selected together so they can be merged.
- Step 3Name files to fix the running order — The merge follows the order of the selected file list and has no in-app reorder control. Prefix sections with zero-padded numbers in your intended order —
01-welcome.md,02-onboarding.md,03-pto-policy.md— so they sort correctly before you select them. - Step 4Keep filename titles on for untitled sections — Leave Add H1 from filename when missing on so any section file lacking a
#heading is titled from its filename. If your sections already carry their own H1s, this option simply leaves them alone. - Step 5Generate the handbook index — Leave Generate Table of Contents on to prepend a
## Table of Contentslinking every heading. This becomes the handbook's master index. Turn it off only if your wiki or PDF template builds its own navigation. - Step 6Run and publish — Click Run MD Merge, then copy or download
merged.md. Publish the Markdown directly, or convert it to PDF or Word for distribution to new hires.
Handbook-assembly options
The only two controls the merger offers, mapped to the handbook problem each one solves.
| Option | Default | Why an ops team uses it |
|---|---|---|
Generate Table of Contents (includeToc) | On | Produces the master index new hires use to navigate to onboarding, PTO, expenses, and incident-response sections |
Add H1 from filename when missing (useFilenames) | On | Titles any section file saved without an H1 (e.g. expenses.md becomes # expenses), so no policy section is left unlabelled |
| Filename-prefix ordering | — | Not an option but the way you set section order: zero-padded prefixes (01-, 02-) force the selected file list into the running order |
Tier limits for handbook merges
Real per-plan caps from the markdown family. A typical ops handbook of a dozen section files fits Pro; very large multi-team handbooks may need a higher tier.
| Plan | Files per merge | Per-file size / characters |
|---|---|---|
| Free | Cannot merge (single file only) | 1 MB / 500,000 |
| Pro | Up to 10 | 10 MB / 5,000,000 |
| Pro + Media | Up to 50 | 50 MB / 20,000,000 |
| Developer | Unlimited | 500 MB / unlimited characters |
Cookbook
Handbook-shaped merges from real ops repos. Section filenames are illustrative.
A six-section handbook in running order
Six team-owned files, prefixed to enforce the running order, merge into one handbook with a master TOC. Each file already has its own H1, so no filename headings are injected.
Selected (in order): 01-welcome.md → `# Welcome` 02-onboarding.md → `# Onboarding` 03-pto-policy.md → `# PTO Policy` 04-expenses.md → `# Expenses` 05-it-security.md → `# IT Security` 06-incident-response.md → `# Incident Response` merged.md starts: ## Table of Contents - [Welcome](#welcome) - [Onboarding](#onboarding) - [PTO Policy](#pto-policy) - [Expenses](#expenses) - [IT Security](#it-security) - [Incident Response](#incident-response)
An untitled policy file is auto-titled
A new team dropped in remote-work.md with no heading. With the filename option on, the merger titles it # remote-work, so it appears in the TOC and reads as a proper section.
Input fragment (remote-work.md): Employees may work remotely up to 3 days per week... In merged.md: # remote-work Employees may work remotely up to 3 days per week...
Sub-section headings show up indented in the TOC
Within 03-pto-policy.md, the H2 sub-headings appear under the section in the TOC, indented two spaces per level, mirroring the policy structure.
pto-policy.md: # PTO Policy ## Accrual ## Carryover ## Requesting Time Off TOC entries: - [PTO Policy](#pto-policy) - [Accrual](#accrual) - [Carryover](#carryover) - [Requesting Time Off](#requesting-time-off)
Merge then export to Word for HR
HR wants a .docx of the handbook. The merger only outputs Markdown, so chain a converter after it.
Step 1 md-merger → merged.md (TOC + 6 sections) Step 2 /markdown-tools/md-to-docx → handbook.docx (For a printable PDF instead: /markdown-tools/md-to-pdf-academic)
Splitting an old monolithic handbook back into sections
Inherited one giant handbook.md? Use the inverse tool to break it into per-section files your teams can own, then merge them back at publish time.
md-splitter (split at H1) on handbook.md → welcome.md, onboarding.md, pto-policy.md, ... Later, md-merger reassembles them into one published handbook.
Edge cases and what actually happens
Sections appear out of running order
By designThe merge follows the order of the selected file list, and there is no reorder control. If onboarding lands after expenses, rename the section files with zero-padded numeric prefixes in the order you want and reselect them.
Free plan can't assemble the handbook
Pro requiredMerging more than one file is a Pro feature. On the free plan, selecting multiple section files stops with Merging multiple files requires a Pro subscription. Upgrade to assemble multi-section handbooks.
Handbook has more sections than the plan cap
Batch limitA large multi-team handbook can exceed the per-merge file cap (Pro 10, Pro + Media 50). Over the cap, the merge stops with Batch limit is N files for your plan. Pre-merge groups of sections within your cap, or move to a higher plan.
Two sections reuse the same heading
Duplicate anchorIf two sections both contain ## Approval, both TOC links resolve to #approval and typically jump only to the first. Rename one heading (## Expense Approval, ## PTO Approval) so each anchor is unique.
A section file already has its own H1
PreservedThe filename-title option only fires when a file has no # line. Sections that already open with # Onboarding keep their heading and are not given a duplicate filename title.
Filename becomes an ugly heading
ExpectedWhen titled from the filename, the heading is the raw stem — pto-policy becomes # pto-policy, hyphens and all. If you want a clean title, add a proper # PTO Policy line to the file before merging, or rename the file.
A `# command` line in a code fence
ExpectedShell snippets in a section (e.g. a fenced block containing # restart the service) are not mistaken for headings — the TOC builder skips lines inside fenced code blocks, so no phantom entries appear.
One oversized section file
Char limitEach section is checked against your plan's per-file character cap. An unusually large policy file over the limit stops the merge with a per-file error. Split it with md-splitter or trim it before merging.
Frequently asked questions
How do I control the order sections appear in?
Order follows the order of the file list you select, and the tool has no drag-to-reorder control. The reliable approach is to prefix each section file with a zero-padded number in your intended running order — 01-welcome.md, 02-onboarding.md, 03-pto-policy.md — so they sort correctly before you select them.
What divides one handbook section from the next?
A Markdown horizontal rule. The merger joins files with \n\n---\n\n, so a --- line sits between every pair of sections. Section titles themselves come from each file's H1 or, when missing, from the filename.
Will untitled section files get a heading?
Yes, as long as Add H1 from filename when missing is on (the default). Any file with no # line gets # <filename> prepended, with the extension removed, so the section is titled and shows up in the Table of Contents.
Does the merge change my heading levels?
No. Heading levels are preserved exactly — a ## Approval workflow stays an H2. If you want to demote section headings (for example to nest them all under the TOC), run each file through md-heading-shifter before merging.
Can I build the handbook on the free plan?
No. md-merger is a Pro tool; merging multiple files requires a Pro subscription. The free plan supports single-file markdown operations only.
How many section files can I merge?
Pro allows up to 10 files per merge, Pro + Media up to 50, and Developer is unlimited. A typical ops handbook fits comfortably within Pro; very large multi-team handbooks may need a higher tier or pre-merging in groups.
How do I turn the handbook into a PDF or Word file?
The merger only outputs Markdown (merged.md). Run that file through a converter: md-to-pdf-academic or md-to-pdf-modern for PDF, or md-to-docx for a Word document.
Is the handbook content uploaded anywhere?
No. The merge runs entirely in your browser. Section files are read locally and combined in the page; the result never touches a server, which matters for internal policy content.
Can I include plain `.txt` notes as sections?
Yes. The drop zone accepts .txt alongside .md, .mdx, and .markdown. A .txt note with no heading is titled from its filename like any untitled section.
How is the master Table of Contents generated?
After merging, the tool scans every heading H1–H6 (skipping headings inside code fences) and prepends ## Table of Contents with a - [Heading](#anchor) line for each, indented two spaces per level. Anchors are the heading text lowercased with spaces turned into hyphens.
How do I split a merged handbook back into per-team files?
Use md-splitter. Splitting at H1 breaks a combined handbook into one file per top-level section, which teams can own individually before you merge them again at publish time.
Some TOC links land on the wrong section — why?
Anchors are derived from heading text only, so two sections sharing a heading (## Overview in both Onboarding and IT Security) generate the same anchor and the link jumps to the first. Make repeated headings distinct to keep navigation accurate.
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.