Does it split at every heading level, or just one?

Just the exact level you choose. Splitting at level 2 (##) only breaks at ## headings; any ### headings underneath stay attached to their parent ## section instead of becoming their own split.

What happens to content before the first matching heading?

It becomes its own leading section, labeled "Untitled", covering anything (like a title or intro paragraph) that appears before the first heading at the chosen level.

Are headings inside fenced code blocks counted?

No, the tool tracks code fences and never splits on a line that merely looks like a heading inside example code.

Markdown File Splitter - Break Up by Heading Online

Overview

Introduction

A single Markdown file can outgrow itself, a changelog spanning years, a guide that's really several chapters, and splitting it by hand means manually finding each heading and cutting the file there.

This does that split automatically at whichever heading level marks a natural section boundary in your document.

What Is Markdown File Splitter?

A document splitter that breaks a Markdown file into sections at every heading of one exact level, leaving deeper subheadings attached to their parent section rather than splitting recursively.

Each resulting section keeps its heading line and everything under it, up to (but not including) the next heading at that same level.

How Markdown File Splitter Works

The document is scanned line by line, tracking fenced code blocks so a heading-like line inside example code is never treated as a split point.

Each time a heading at the exact chosen level is found, the current section is closed off and a new one begins, keyed by that heading's text.

When To Use Markdown File Splitter

Use it when a long changelog, guide, or reference doc needs to become several smaller files, one per top-level section.

It's also useful for extracting just one section (a single chapter or entry) out of a much larger document without manually scrolling to find its boundaries.

Often used alongside Markdown File Merger, Markdown Header Extractor and Markdown Formatter & Pretty Printer.

Features

Advantages

Splits at an exact heading level, so nested subheadings stay grouped with their parent section instead of fragmenting further.
Never splits inside a fenced code block, even one containing heading-like text.
Each section gets its own copy and download button immediately.

Limitations

Doesn't bundle the results into a single .zip archive; each section downloads individually.
Content before the first matching heading is grouped as one "Untitled" section rather than being distributed elsewhere.

Examples

Splitting at level-2 headings

Input

# Guide

Intro text.

## Setup

Setup text.

## Usage

Usage text.

Output

Untitled: "# Guide\n\nIntro text."
Setup: "## Setup\n\nSetup text."
Usage: "## Usage\n\nUsage text."

The intro before the first ## heading becomes its own Untitled section; each ## heading starts a new one.

Best Practices & Notes

Best Practices

Choose the heading level that actually marks your document's natural sections; splitting at the wrong level either produces one giant section or too many tiny ones.
Run Markdown Validator first if you're not sure the document's heading levels are used consistently.
Use Combine Markdown Files afterward if you need to merge a subset of the resulting sections back together differently.

Developer Notes

The heading match uses an exact-count regex, `^#{level}[ \t]+`, not `^#{1,level}`, which is what guarantees splitting at level 2 doesn't also trigger on level-1 or level-3 headings, only exact ## lines.

Markdown File Splitter Use Cases

Breaking a long changelog into one file per version or era
Splitting a multi-chapter guide into individual chapter files
Extracting a single section out of a much larger reference document

Common Mistakes

Choosing a heading level that doesn't actually appear consistently in the document, resulting in one large unsplit section.
Expecting a zip download; each split section is downloaded as its own individual file.

Tips

If the split produces just one big section, try a shallower heading level (like 1 instead of 2).
Check the "Untitled" leading section for anything worth keeping, like a document-level title or introduction, before discarding it.

Markdown File Splitter