How to bulk merge many markdown files at once
- Step 1Confirm your plan's file cap — A 50-file merge requires Pro + Media (cap 50) or Developer (unlimited). Pro caps each merge at 10 files. If your batch exceeds your cap, plan to merge in groups (see the batch-limit edge case) or upgrade.
- Step 2Adopt a zero-padded naming scheme — At scale, order is everything, and the merge follows the selected file list with no reorder control. Rename files with zero-padded prefixes wide enough for the batch —
001-,002-, ...,050-— so all 50 sort correctly in one selection. - Step 3Switch to Upload mode and select the batch — Use the Upload file tab and select the whole batch at once (or drag the files onto the drop zone). The drop zone accepts
.md,.mdx,.markdown, and.txt. - Step 4Set the heading and TOC options — Leave Add H1 from filename when missing on so untitled files are titled, and Generate Table of Contents on to index the whole batch. For a very large merge the TOC can be long — that is expected and is the navigation payoff.
- Step 5Run the merge — Click Run MD Merge. Everything processes locally in the tab; a large batch may take a moment as each file is read and concatenated, then indexed.
- Step 6Download and convert — Download
merged.md, then run it through a converter — md-to-html for a single-page manual, or md-to-pdf-modern for a PDF — to produce the final artifact.
File-count caps by plan
The real per-merge file limits from the markdown family. A genuine 50-file merge is a Pro + Media (or Developer) operation.
| Plan | Max files per merge | Per-file size / characters |
|---|---|---|
| Free | Cannot merge (1 file only) | 1 MB / 500,000 |
| Pro | 10 | 10 MB / 5,000,000 |
| Pro + Media | 50 | 50 MB / 20,000,000 |
| Developer | Unlimited | 500 MB / unlimited characters |
Bulk-merge behaviour at scale
How the merger behaves across a large batch, and what stays your responsibility.
| Aspect | Behaviour | Your job at scale |
|---|---|---|
| Order | Follows the selected file list | Use zero-padded prefixes wide enough for the batch (001- … 050-) |
| Separator | --- rule between every pair of files | Nothing — it is automatic and not configurable |
| Untitled files | Titled from filename (useFilenames on) | Name files cleanly so the generated headings read well |
| TOC | Indexes every heading across the batch | Expect a long index for a large merge; turn off if a converter builds its own |
| Per-file char limit | Checked per file against the plan cap | Split oversized articles with md-splitter before merging |
Cookbook
Bulk merges at documentation scale. Filenames show the zero-padded scheme that keeps large batches ordered.
A 50-file docs set on Pro + Media
Fifty articles, named with three-digit prefixes, merge into one manual with a full TOC. This needs Pro + Media (cap 50) or Developer.
Selected (001-050, sorted): 001-getting-started.md 002-installation.md ... 050-changelog.md merged.md: ## Table of Contents - [Getting Started](#getting-started) - [Installation](#installation) ... (one entry per heading, all 50 files) - [Changelog](#changelog) # Getting Started ... --- # Installation ...
A batch larger than your cap, merged in groups
Need to combine 30 files on Pro (cap 10)? Merge in groups of ten, then merge the three group files. The three intermediate files still total three — within the cap.
Pro cap = 10 files. Pass 1: merge 001-010 → part-1.md Pass 2: merge 011-020 → part-2.md Pass 3: merge 021-030 → part-3.md Pass 4: merge part-1.md, part-2.md, part-3.md → manual.md (Or upgrade to Pro + Media for a single 30-file merge.)
Exceeding the cap returns an explicit error
Selecting more files than your plan allows stops before any work, with the cap stated in the message.
Plan: Pro (cap 10). Selected: 14 files. Error: Batch limit is 10 files for your plan. → Split into batches of 10 or fewer, or upgrade.
Raw concatenation for a downstream build
Feeding a static-site generator that builds its own nav? Turn off the TOC for a clean concatenation with separators and filename headings only.
Options: includeToc = off, useFilenames = on merged.md: # 001-getting-started ... --- # 002-installation ... (no Table of Contents block)
Merge then publish as one HTML page
Produce a single-page manual from the whole batch by converting after the merge.
Step 1 md-merger → merged.md (TOC + all files) Step 2 /markdown-tools/md-to-html → one-page manual.html (For PDF: /markdown-tools/md-to-pdf-modern)
Edge cases and what actually happens
Selecting more files than your plan allows
Batch limitThe merge checks the file count first. Over your cap it stops with Batch limit is N files for your plan. (Pro 10, Pro + Media 50). Merge in groups within the cap and combine the group files, or upgrade for a single large merge.
Trying a bulk merge on the free plan
Pro requiredBulk merging is firmly a paid feature. On the free plan, selecting more than one file stops with Merging multiple files requires a Pro subscription.
Large batch comes out scrambled
By designOrder follows the selected file list, and there is no reorder control — at 50 files this is unforgiving. Use zero-padded prefixes wide enough for the batch (001-, not 1-) so files sort numerically rather than lexically (1, 10, 2).
Inconsistent prefix widths break sorting
Ordering pitfallMixing 1-, 2-, 10- sorts as 1, 10, 2 in most file pickers. Pad all prefixes to the same width (01-, 02-, 10-, or 001- for 100+ files) so the selection order matches your intended sequence.
Repeated headings across many files
Duplicate anchorAcross a large batch, headings like ## Overview or ## Examples recur. All identical headings produce the same anchor, so those TOC links collapse onto the first. For a clean index, make recurring section headings file-specific.
One file in the batch is too large
Char limitEach file is checked against your plan's per-file character cap (Pro 5,000,000; Pro + Media 20,000,000). A single oversized article over the cap fails the whole merge with a per-file error naming it. Split it with md-splitter and retry.
A very long generated TOC
ExpectedA 50-file merge can produce a long Table of Contents — one entry per heading across every file. That is by design and is the navigation benefit. If a downstream build generates its own navigation, turn the TOC off.
Untitled files get filename headings
PreservedIn a large batch some files may lack an H1. With the filename option on, each gets # <filename> so no section is nameless; files that already have an H1 keep it. Name files cleanly so the auto-titles read well.
Frequently asked questions
Can I really merge 50 Markdown files at once?
Yes, on Pro + Media, whose markdown batch cap is 50 files per merge; Developer is unlimited. Pro caps each merge at 10 files. So a genuine 50-file merge requires Pro + Media or higher — on Pro you would merge in groups of ten and then combine the group files.
What happens if I select more files than my plan allows?
The merge stops before doing any work with Batch limit is N files for your plan. where N is your cap (Pro 10, Pro + Media 50). Reduce the selection to fit the cap, merge in batches, or upgrade.
How do I keep a large batch in the right order?
The merge follows the order of the selected file list and has no in-app reorder control. Use zero-padded numeric prefixes wide enough for the batch — 001-, 002-, ..., 050- — so files sort numerically rather than lexically (which would order 1, 10, 2).
Why do my files sort as 1, 10, 2 instead of 1, 2, 3?
Unpadded numeric prefixes sort lexically, so 10- comes before 2-. Pad every prefix to the same width (01-, 02-, 10-, or three digits for 100+ files) so the file picker returns them in numeric order, which is the order they merge in.
Does the merge change my headings across all the files?
No. Heading levels are preserved exactly in every file. If you need to demote headings consistently across the batch, run each file through md-heading-shifter before merging.
What separates the files in the combined document?
A Markdown horizontal rule — the merger joins files with \n\n---\n\n, so a --- line sits between every pair of files, keeping article boundaries clear even across dozens of sections.
Will the Table of Contents cover all the files?
Yes. With Generate Table of Contents on, the tool indexes every heading H1–H6 across the entire merged batch into one ## Table of Contents at the top. For a large merge that index can be long — that is the navigation payoff. Turn it off if a downstream build creates its own.
Is there a size limit per file in a bulk merge?
Yes — each file is checked against your plan's per-file character cap (Pro 5,000,000; Pro + Media 20,000,000; Developer unlimited) and size cap (Pro 10 MB; Pro + Media 50 MB; Developer 500 MB). One oversized file fails the whole merge; split it with md-splitter first.
Does a 50-file merge upload anything to a server?
No. The entire merge runs in your browser. All files are read locally and combined in the page, so even a large documentation set never leaves your machine.
How do I produce a single PDF or HTML manual from the batch?
The merger outputs Markdown only. Convert the combined file with md-to-html for a single-page manual, md-to-pdf-modern for a PDF, or md-to-docx for a Word document.
Can I split a big merged manual back into files?
Yes. md-splitter breaks one Markdown file into several at a chosen heading level — split at H1 to recover one file per top-level section, the inverse of a bulk merge.
Why do some TOC links in a big merge point to the wrong place?
Anchors are generated from heading text only. Across many files, recurring headings (## Overview, ## Examples) collide on the same anchor, so those links jump to the first occurrence. Make recurring section headings file-specific to keep the large index 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.