How to demote every h1 to h2 for clean embedding
- Step 1Paste or drop the doc — Load the Markdown file that has its own
#H1. Free accepts up to 1 MB / 500,000 characters in a single file. - Step 2Set delta to +1 — Enter
+1in the delta field (this is also the default). One level is the standard demotion for embedding under a host H1. - Step 3Run the demotion — Process the document. Every recognized ATX heading drops one level in a single pass; everything else is copied verbatim.
- Step 4Verify the new top level — Confirm the former
#H1 is now##and there is no remaining#heading in the body (frontmatter aside). - Step 5Check headings near H6 — Any heading that was already H6 stays H6 (clamped). Review deep sections so you know whether two levels collapsed into one.
- Step 6Embed and rebuild navigation — Paste the demoted Markdown into the host. If the host builds a table of contents by depth, regenerate it with md-toc-generator.
Heading map for delta +1 (demote one level)
Each level moves down one. H6 is the floor: it cannot demote further and clamps in place.
| Before | After (delta +1) | Markdown before | Markdown after |
|---|---|---|---|
| H1 | H2 | # | ## |
| H2 | H3 | ## | ### |
| H3 | H4 | ### | #### |
| H4 | H5 | #### | ##### |
| H5 | H6 | ##### | ###### |
| H6 | H6 (clamped) | ###### | ###### |
Why a single H1 matters
Reasons a duplicate H1 causes problems, and what demoting by one fixes.
| Concern | Symptom of duplicate H1 | After demote +1 |
|---|---|---|
| Accessibility | Screen readers announce two document titles, breaking heading navigation | One H1 (the host's); embedded content nests under it |
| Document outline | Outline algorithms show two top-level nodes | Single outline root with a clean tree below |
| Docs theme styling | Both H1s render at hero size, doubling visual weight | Embedded headings render at section size (##+) |
| TOC generation | Two competing top levels in the contents | One top level; depth filters behave predictably |
Lines this transform never changes
Demotion runs only on recognized ATX headings; everything below is passed through unchanged.
| Line | Demoted? | Reason |
|---|---|---|
# Title | Yes (becomes ## Title) | Valid ATX heading |
#NoSpace | No | No space after the hash |
# step inside a ``` fence | No | Inside a fenced code block |
---…--- frontmatter | No | Split off before processing |
Title over ===== | No | Setext headings are not recognized |
Cookbook
Before/after demotions at delta +1 — the exact transform you run before embedding a doc under a host H1.
Single-H1 README embedded into a docs page
Your README opens with # Project. The docs theme already renders the page title as H1, so demote everything one level before pasting it in.
Input: # Project ## Overview ## Install Output (delta = +1): ## Project ### Overview ### Install
Deeply nested doc hits the H6 floor
A doc that already reaches H6 will collapse its two deepest levels into one when demoted, because H6 is the floor.
Input: ##### Config ###### Advanced Output (delta = +1): ###### Config ###### Advanced
Frontmatter survives the demotion
YAML frontmatter is split off first, so its keys are untouched while the body H1 demotes to H2.
Input: --- title: Release Notes weight: 3 --- # Release Notes ## v2.0 Output (delta = +1): --- title: Release Notes weight: 3 --- ## Release Notes ### v2.0
A code sample with a comment line
The # build the image line is inside a fenced block, so it is preserved while the real headings demote.
Input: # Deployment ```sh # build the image docker build . ``` Output (delta = +1): ## Deployment ```sh # build the image docker build . ```
Reversing a demotion
Run delta -1 to undo a +1 demotion. Anything that did not hit the H6 clamp returns to its original level.
After demote (delta +1): ## Project ### Overview Undo (delta = -1): # Project ## Overview
Edge cases and what actually happens
Document has more than one H1
By designIf the source has several # H1s, all of them demote to ##. The tool does not detect or warn about multiple H1s; it applies the same +1 shift to every recognized heading. After demotion the document has zero # headings in its body, which is what you want for embedding.
Document already starts at H2
ExpectedDemoting a doc whose top heading is already ## pushes it to ###. If you actually wanted the top to become H2, you do not need to shift at all — a delta of +1 here would over-demote. Inspect the current top level first.
Heading already at H6
ClampedAn H6 heading stays at H6 because min(6, level + 1) caps it. If the doc had both H5 and H6 sections, the H5 becomes H6 and now sits at the same level as the original H6 — two levels merged into one.
Setext H1 (`Title` over `=====`)
Not supportedAn underline-style H1 is not recognized and will not demote, leaving a stray top-level heading after the rest of the doc shifts. Convert Setext headings to ATX first, for example with md-prettifier.
`#` inside a fenced code block
PreservedLines inside a ``` fence are copied verbatim, so a shell comment like # install` never demotes. This keeps runnable code samples correct.
Frontmatter present
PreservedYAML (---) or TOML (+++) frontmatter is split off and re-prepended unchanged; only the body demotes. A # inside frontmatter is never touched.
`#NoSpace` line
PreservedA hash with no following space is not a heading per CommonMark and is not demoted. So #tag or #!shebang-style lines pass through unchanged.
Anchor links into demoted headings
PreservedAnchor slugs come from heading text, not level, so [link](#overview) still resolves after ## Overview becomes ### Overview. Only depth-filtered TOCs may need regenerating.
Empty document or no headings
ExpectedIf there are no recognized headings, the output equals the input — the body is copied through and frontmatter re-attached. No error is raised.
File over the tier character limit
RejectedFree is limited to 1 MB / 500,000 characters per file. Larger docs are rejected up front; upgrade to Pro (10 MB / 5,000,000 characters) or split with md-splitter.
Frequently asked questions
How do I demote H1 to H2?
Set the delta to +1 (the default) and run. A positive delta adds a #, so every # H1 becomes ##, and the rest of the hierarchy follows: ## to ###, and so on.
Why should a document have only one H1?
A single H1 is the accessibility and outline standard: screen readers and document-outline algorithms expect one top-level title. When you embed content under a host that already has an H1, demoting your headings keeps that single-H1 structure intact.
Does demoting change my heading text?
No. Only the leading # count changes. The heading text, the space after the hashes, and all body content are preserved exactly.
What if some headings are already at H6?
They stay at H6 — the depth is clamped with min(6, ...). If you had both H5 and H6 sections, the H5 becomes H6 and now shares a level with the original H6, so two levels merge.
Can I undo a demotion?
Yes — run again with delta = -1 to promote everything back. The only exception is headings that hit the H6 clamp; their original level was lost at the boundary and cannot be recovered.
Are code blocks and frontmatter safe?
Yes. Lines inside fenced ``` ``` blocks are copied verbatim, and YAML/TOML frontmatter is split off and re-attached unchanged. Only real ATX headings in the body demote.
Will demoting break my in-page links?
No. Anchor slugs are based on heading text, not level, so links like [jump](#install) keep working. Only a depth-based table of contents may need rebuilding via md-toc-generator.
What about Setext (underline) H1s?
They are not recognized and will not demote. Convert them to ATX # headings first — md-prettifier can normalize heading style.
Can I demote several files at once?
No — one file at a time. Run each separately, or combine them first with md-merger and demote the merged result.
My doc has multiple H1s — what happens?
All of them demote to ##. The tool does not flag duplicate H1s; it just applies the same +1 to every heading, which removes all body-level H1s — exactly what embedding needs.
Is the demoted file uploaded anywhere?
No. Processing is entirely browser-side on every tier, so the document never leaves your machine.
What is the size limit?
Free allows 1 MB / 500,000 characters in a single file. Pro raises it to 10 MB / 5,000,000 characters, Pro-media to 50 MB / 20,000,000, and Developer to 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.