How to promote markdown headings after extracting a section
- Step 1Extract the section — Split or copy the section into its own file. If you used md-splitter, each output retains the parent's heading depths — that is what we are about to fix.
- Step 2Find the section's current top level — Look at the shallowest heading in the extracted file. If it is
##(H2), the section was nested one level deep. - Step 3Set a negative delta — Enter the negation of that depth offset:
-1to bring an H2 top up to H1,-2for an H3 top, and so on. The accepted range is -5 to +5. - Step 4Run the promotion — Process the file. Every recognized ATX heading rises by the chosen amount in a single pass; non-heading lines, code blocks, and frontmatter are untouched.
- Step 5Confirm the new H1 — Verify the section now opens with a single
#H1 and the rest of the tree sits below it cleanly. - Step 6Generate a standalone TOC — Add a fresh table of contents for the new standalone doc with md-toc-generator, now that depths reflect a top-level document.
Which negative delta to use
Pick the delta that brings the section's shallowest heading up to H1.
| Section's current top level | Delta to use | Resulting top level |
|---|---|---|
H2 (##) | -1 | H1 (#) |
H3 (###) | -2 | H1 (#) |
H4 (####) | -3 | H1 (#) |
H5 (#####) | -4 | H1 (#) |
H6 (######) | -5 | H1 (#) |
Promotion applied across a section (delta -1)
A section extracted from under an H2 parent, promoted by one level so its top becomes H1.
| Before (in parent) | After (delta -1) | Markdown before | Markdown after |
|---|---|---|---|
| H2 section title | H1 | ## | # |
| H3 subsection | H2 | ### | ## |
| H4 detail | H3 | #### | ### |
| H1 (if any leaked in) | H1 (clamped) | # | # |
What promotion does not change
Only recognized ATX headings promote; the rest is copied through verbatim.
| Line | Promoted? | Reason |
|---|---|---|
## Section | Yes (becomes # Section) | Valid ATX heading |
# Already top | No (clamped at H1) | Cannot promote above H1 |
#NoSpace | No | No space after the hash |
## step in a ``` fence | No | Inside a fenced code block |
---…--- frontmatter | No | Split off before processing |
Cookbook
Real promotions of extracted sections. Choose the delta that lifts the section's top heading to H1.
Section that started at H2 (delta -1)
The most common extraction: a section that lived under a ## parent becomes a standalone doc opening at #.
Input (extracted, still parent-relative): ## Authentication ### API Keys ### OAuth Output (delta = -1): # Authentication ## API Keys ## OAuth
Section that started at H3 (delta -2)
A deeper section, two levels down in the parent, promoted by two so its top becomes H1.
Input: ### Webhooks #### Retries ##### Backoff Output (delta = -2): # Webhooks ## Retries ### Backoff
A stray H1 leaked into the extract (clamping)
If the extracted section accidentally includes a parent-level #, promoting clamps it at H1 — it cannot rise further, so the section may end up with two H1s.
Input: # Parent Title (leaked) ## Real Section ### Detail Output (delta = -1): # Parent Title (leaked) # Real Section ## Detail
Code samples in the extracted section
A ## line inside a fenced block (for example, a Markdown-about-Markdown sample) is preserved while real headings promote.
Input: ## Formatting ```md ## This is sample output ``` Output (delta = -1): # Formatting ```md ## This is sample output ```
Split then promote each piece
Run the splitter to cut a big doc into per-section files, then promote each one. This snippet shows one resulting file after promotion.
After md-splitter (one output file): ## Billing ### Invoices After promote (delta = -1): # Billing ## Invoices
Edge cases and what actually happens
Section already opens at H1
ClampedIf the extracted section's top is already #, a negative delta cannot raise it — max(1, ...) keeps it at H1. Deeper headings still promote, which can flatten the top of the hierarchy. Inspect the current top level before choosing a delta.
Stray parent H1 inside the extract
By designIf the copy/split accidentally captured a parent # heading, promotion clamps it at H1 while the intended section top also rises to H1 — leaving two H1s. Trim the leaked heading before promoting, or promote then delete the stray.
Over-promoting (delta too negative)
ClampedChoosing -3 for a section that started at H2 drives the top below H1; the clamp pins it at H1, so the result is the same as -1 for the top heading but flattens any sub-levels that also hit the floor. Match the delta to the actual nesting depth.
Section has uneven starting levels
ExpectedIf the section opens at H2 but contains a deeper jump (say it skips to H4), all headings shift by the same delta — relative gaps are preserved, including the skipped level. Promotion does not fix non-sequential heading jumps.
`#` inside a fenced code block
PreservedLines inside a ``` ``` fence are copied verbatim, so heading-like lines in a Markdown sample stay exactly as written even when surrounding headings promote.
Setext headings in the section
Not supportedUnderline-style (===/---) headings are not recognized and will not promote. Convert them to ATX first with md-prettifier so the whole section shifts uniformly.
Frontmatter carried over from the parent
PreservedIf the extracted file kept the parent's YAML/TOML frontmatter, it is split off and re-attached unchanged. Promotion only touches body headings; edit frontmatter separately if the standalone doc needs different metadata.
`#NoSpace` line
PreservedA hash with no following space is not a heading and is never promoted, matching CommonMark. Hashtags and shebang-like lines pass through unchanged.
Empty extract or no headings
ExpectedAn extract with no recognized headings is copied through unchanged — no error. Useful when a section is mostly prose or code.
Extract exceeds the tier limit
RejectedFree caps a single file at 1 MB / 500,000 characters. Large extracts are rejected before processing; upgrade to Pro (10 MB / 5,000,000 characters) or split further with md-splitter.
Frequently asked questions
How do I promote headings after extracting a section?
Use a negative delta. If the section's shallowest heading is ## (H2), set delta = -1 so it becomes # (H1); for an H3 top use -2, and so on. Every heading rises by the same amount.
How do I know which delta to use?
Find the shallowest heading in the extracted file and subtract enough to make it H1. H2 top → -1, H3 top → -2, H4 top → -3. The accepted range is -5 to +5.
What if I over-promote?
Headings clamp at H1 — max(1, level + delta) — so the top will not go invalid, but sub-levels that also hit the floor flatten together. Match the delta to the real nesting depth to avoid collapsing structure.
Does the relative hierarchy stay intact?
Yes. Every heading shifts by the same delta, so the gaps between levels are preserved. A clean H2/H3/H4 section becomes a clean H1/H2/H3 standalone.
Can I combine this with the splitter?
Yes — that is the intended workflow. Run md-splitter to cut the document into per-section files, then promote each output here to standalone levels.
What if my section has mixed or skipped levels?
All headings shift by the same delta, so a skipped level (for example H2 jumping to H4) stays skipped. Promotion adjusts depth uniformly; it does not renumber or fix non-sequential jumps.
Are code blocks and frontmatter preserved?
Yes. Lines inside fenced ``` ``` blocks and any YAML/TOML frontmatter are passed through unchanged; only recognized ATX headings in the body promote.
What about a stray parent H1 that got copied in?
It clamps at H1 and so does the intended section top, leaving two H1s. Remove the leaked heading before or after promoting to keep a single H1.
Will promotion break anchor links inside the section?
No. Anchor slugs come from heading text, not level, so internal links keep resolving. Regenerate a depth-based TOC with md-toc-generator if the standalone doc needs one.
Can I promote several extracted files at once?
No — one file per run. Promote each split output individually, or merge related sections first with md-merger.
Does it support Setext underline headings?
No, only ATX # headings. Convert Setext to ATX first with md-prettifier so the whole section promotes consistently.
What is the file size limit?
Free allows 1 MB / 500,000 characters per file; Pro 10 MB / 5,000,000; Pro-media 50 MB / 20,000,000; Developer 500 MB with no character cap.
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.