How to combine many markdown files into one
- Step 1Switch the tool to Upload mode — Merging needs multiple files, so use the Upload file tab rather than Paste text — paste mode wraps your text in a single
input.md, which means nothing to merge. The drop zone accepts.md,.mdx,.markdown, and.txt. - Step 2Select every file you want to merge — Click the drop zone (or drag files onto it) and pick all the files at once. The merger processes them in the order your operating system's file picker returns them — there is no in-app drag-to-reorder control, so name files to sort predictably (see the next step).
- Step 3Control order with a numeric filename prefix — Because order follows the file list, prefix names with
01-,02-,03-(zero-padded) so they sort the way you want before you select them.intro.md,setup.md,usage.mdmay not sort alphabetically into reading order;01-intro.md,02-setup.md,03-usage.mdalways will. - Step 4Decide whether to title untitled files — Leave Add H1 from filename when missing on (default) so any file lacking a
#line gets# <filename-stem>prepended. Turn it off only when your files already have their own H1 and you do not want filename headings injected. - Step 5Choose whether to generate a Table of Contents — Leave Generate Table of Contents on (default) to prepend
## Table of Contentswith a link for every heading H1–H6. Turn it off for a raw concatenation with---separators and no index — useful when a downstream tool generates its own navigation. - Step 6Run, then copy or download merged.md — Click Run MD Merge. The result panel shows the combined Markdown as
merged.md; use Copy to grab the text or Download to save the file. Feed it into a converter sibling next if you need PDF, DOCX, or HTML.
What each md-merger option does
The merger exposes exactly two checkboxes plus an API-only field. There is no separator picker, no order control, and no heading-shift option — those live in other tools.
| Option | Default | Effect on the merged output |
|---|---|---|
Generate Table of Contents (includeToc) | On | Scans every heading H1–H6 in the merged body (skipping headings inside fenced code blocks) and prepends ## Table of Contents with - [Heading](#anchor) links, indented two spaces per level below the lowest level seen |
Add H1 from filename when missing (useFilenames) | On | For each file with no line matching # (an H1), prepends # <filename> with the .md / .mdx / .markdown / .txt extension removed. Files that already have any H1 are left untouched |
parts (API only) | — | On the public API, an array of extra Markdown bodies merged after the request's input. Not a UI control — the in-browser tool merges the files you drop instead |
Merge behaviour and tier limits
How the merger joins files, and the real per-plan file-count and per-file size/character ceilings from the markdown family limits.
| Aspect | Behaviour / limit | Notes |
|---|---|---|
| File separator | \n\n---\n\n between each pair of files | A Markdown horizontal rule — renders as a <hr>, not an H2 heading |
| File order | Order of the selected file list | No in-app reorder; control it with zero-padded numeric filename prefixes |
| Free tier | Merging more than one file requires Pro | md-merger is a Pro tool; the free plan cannot merge a batch |
| Pro file count | Up to 10 files per merge | Per-file: 10 MB / 5,000,000 characters |
| Pro + Media file count | Up to 50 files per merge | Per-file: 50 MB / 20,000,000 characters |
| Developer file count | Unlimited files | Per-file: 500 MB, no character cap |
Cookbook
Concrete before/after merges. The arrow blocks show the files going in and the structure that comes out.
Two titled files merged with a TOC
Both files already start with an H1, so no filename headings are injected. The merger joins them with a --- rule and builds a Table of Contents from both H1s plus any sub-headings.
Inputs: intro.md → starts with `# Introduction` install.md → starts with `# Installation` + `## Requirements` merged.md (TOC on, default): ## Table of Contents - [Introduction](#introduction) - [Installation](#installation) - [Requirements](#requirements) # Introduction ... --- # Installation ## Requirements ...
An untitled fragment gets a filename heading
notes.md has no # line, so with the filename option on, the merger prepends # notes. The extension is stripped to form the heading text.
Inputs: overview.md → `# Overview` notes.md → (no H1, body starts with prose) merged.md: # Overview ... --- # notes (prose from notes.md)
Raw concatenation with no index
Turn off Generate Table of Contents when a downstream build (or a converter that injects its own nav) will handle navigation. You still get the --- separators and the filename headings.
Options: includeToc = off, useFilenames = on merged.md: # chapter-1 ... --- # chapter-2 ...
Ordering a docs folder with numeric prefixes
Alphabetical file order rarely matches reading order. Rename with zero-padded prefixes before selecting so the merge comes out in sequence.
Rename: getting-started.md → 01-getting-started.md configuration.md → 02-configuration.md api.md → 03-api.md Select all → merged.md reads 01 → 02 → 03 top to bottom.
Merge then convert to PDF
md-merger only produces Markdown. To ship a single PDF, merge first, then run the merged file through a converter sibling.
Step 1 md-merger → merged.md (TOC + sections)
Step 2 /markdown-tools/md-to-pdf-modern → styled PDF
or /markdown-tools/md-to-docx → Word .docxEdge cases and what actually happens
Trying to merge on the free plan
Pro requiredmd-merger is a Pro tool. Selecting more than one file on the free plan stops with Merging multiple files requires a Pro subscription. Upgrade to merge a batch; the free plan is limited to single-file markdown operations.
More files than your plan allows
Batch limitEach plan caps the number of files per merge: Pro 10, Pro + Media 50, Developer unlimited. Exceeding it stops with Batch limit is N files for your plan. Split the job into batches within your cap, or upgrade for a larger batch.
Files come out in the wrong order
By designThe merger uses the order of the selected file list — there is no drag-to-reorder control in the tool. If the sequence is wrong, rename files with zero-padded numeric prefixes (01-, 02-, ...) and reselect so they sort into reading order before the merge.
Pasting instead of uploading
Single inputPaste mode wraps your text in one input.md, so there is nothing to merge — you get that single document back. To merge several files, switch to the Upload tab and select them all at once.
Duplicate heading text across files
Duplicate anchorAnchors are derived purely from heading text (lowercased, spaces to hyphens). If two files both contain ## Overview, both TOC links point to #overview, and in most renderers the link jumps to the first occurrence only. Rename one heading to keep the anchors distinct.
A file already starts with an H1
PreservedThe filename option only acts when no # line is present. A file that already opens with # My Title keeps its own heading and is not given a second filename H1, so titled files merge cleanly.
Headings inside code blocks
ExpectedThe TOC builder tracks fenced code blocks and skips any # lines inside them. A shell comment like # install in a fenced block will not become a phantom TOC entry.
A single file over the per-file character limit
Char limitEach file is checked against your plan's character limit (Pro 5,000,000; Pro + Media 20,000,000; Developer unlimited). A file over the cap stops the merge with a per-file error naming that file. Split the oversized file with md-splitter first.
Frequently asked questions
What separator goes between merged files?
A Markdown horizontal rule: the merger joins files with \n\n---\n\n, so each section is divided by a --- line that renders as a horizontal rule. It does not insert an H2 separator — section titles come from each file's own H1 or, when missing, from the filename.
Does it reorder my files?
No. Files are merged in the order the selected file list provides them. There is no drag-to-reorder control inside the tool, so the reliable way to set order is to prefix filenames with zero-padded numbers (01-, 02-, 03-) before you select them.
Why does each section have a heading I did not write?
With Add H1 from filename when missing on (the default), any file that has no # line gets # <filename> prepended, using the filename with its extension removed. Turn the option off if your files already have headings and you do not want filename titles injected.
How is the Table of Contents built?
After merging, the tool scans every heading H1–H6 in the body (skipping headings inside fenced code blocks) and writes a ## Table of Contents list at the very top. Each entry is - [Heading text](#anchor), indented two spaces per heading level, with the anchor formed by lowercasing the heading and converting spaces to hyphens.
Can I merge files on the free plan?
No. md-merger is a Pro feature — merging more than one file requires a Pro subscription. The free plan is limited to single-file markdown tools.
How many files can I merge at once?
It depends on your plan: Pro allows up to 10 files, Pro + Media up to 50, and Developer is unlimited. Going over the cap returns Batch limit is N files for your plan.
Does merging change my heading levels?
No. The merger preserves every heading exactly as written — it never shifts or renumbers levels. If you want section headings demoted (for example, so each file's H1 becomes an H2 under the TOC), run each file through md-heading-shifter before merging.
What output format do I get?
A single Markdown file named merged.md. You can copy the text or download the file. To ship a PDF, Word, or HTML deliverable, run the merged file through a converter such as md-to-pdf-modern, md-to-docx, or md-to-html.
Is anything uploaded to a server?
No. Markdown tools run entirely in your browser. The files you select are read locally, merged in the page, and the result stays in the tab until you download or copy it.
What file types can I drop in?
The drop zone accepts .md, .mdx, .markdown, and .txt. Plain .txt notes are merged as-is, and if they lack a heading they get a filename H1 like any other untitled file.
Can I undo a merge — split the file back out?
Yes, use the inverse tool: md-splitter breaks one Markdown file into several at a chosen heading level. It is the natural counterpart to the merger when you need to fan a combined document back into per-section files.
The merged TOC links don't all jump correctly — why?
TOC anchors are generated from heading text alone, so two identically named headings in different files produce the same anchor. Most renderers then send both links to the first occurrence. Give duplicate headings distinct text, or shift their levels so they read differently in context.
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.