Headings and cross-references
Section wrapping, id derivation and normalization, implicit and collapsed heading references.
Generated from resources/examples/edge-cases/, resources/examples/core.md and resources/examples/extensions.md - edit the cases there, not here. Each case links the conformance fixture it produces.
Single-line headings
10 conformance fixtures
A heading ends at the newline. Nothing folds into it: the next line begins whatever block it begins, exactly as after any other closed block. This diverges from djot deliberately — djot folds a following plain line into the heading, which is a silent corruption for anyone arriving from Markdown, and divergence-from-djot §7 already broke from djot on the mirror case. A ^ … caption line is no exception: it does not fold in, and it does not attach either, because a heading is not one of §4's captionable hosts - it opens an ordinary paragraph. The heading id is built from the single line. (Setext underline headings remain intentionally excluded.)
# Title
outside<section id="Title">
<h1>Title</h1>
<p>outside</p>
</section>Repeated headings are simply separate headings — the # count no longer decides whether one folds into another.
## A
## still A
# B<section id="A">
<h2>A</h2>
</section>
<section id="still-A">
<h2>still A</h2>
</section>
<section id="B">
<h1>B</h1>
</section>A list marker — bullet or ordered — ends the heading and starts a sibling list.
# Title
- item<section id="Title">
<h1>Title</h1>
<ul>
<li>item</li>
</ul>
</section>An ordered marker ends the heading the same way (symmetric with the bullet).
# Title
1. one<section id="Title">
<h1>Title</h1>
<ol>
<li>one</li>
</ol>
</section>A marker followed by whitespace only is not a heading — the content after the required space must carry at least one non-whitespace character, so the trailing spaces leave the line as paragraph text.
#<p>#</p>A trailing hash run is heading text. The Markdown target escapes the run's first # so a CommonMark reader does not strip it as a closing sequence (PART 11 §8a M1f).
# a ##<section id="a">
<h1>a ##</h1>
</section>A single trailing hash is a run of one.
# a #<section id="a">
<h1>a #</h1>
</section>Only the trailing run closes a Markdown heading, so a run with text after it stays bare.
# a ### b ###<section id="a-b">
<h1>a ### b ###</h1>
</section>The run has no length limit.
# a #######<section id="a">
<h1>a #######</h1>
</section>A heading inside a container is a heading line too.
> - a
>
> ### b ###<blockquote>
<ul>
<li><p>a</p>
<h3 id="b">b ###</h3>
</li>
</ul>
</blockquote>A heading marker opens at an indented top-level column
2 conformance fixtures
An indented #-line opens a heading at top level (carve#3885). Within a container the column is measured after the container markers, so > # H is a quoted heading.
# H<section id="H">
<h1>H</h1>
</section>An indented marker with more hashes opens a heading of that level.
## H<section id="H">
<h2>H</h2>
</section>Cyclic cross-reference resolves to one level
3 conformance fixtures
A </#id> cross-reference resolves to ONE level: it links to the target and adopts the target's text. A cross-reference in that text contributes its own target's visible inline text without another link; references inside that target do not expand again (PART 9 §19). This keeps a self-reference or a mutual cycle finite.
A self-reference resolves once:
# A </#A><section id="A">
<h1>A <a href="#A">A A </a></h1>
</section>A mutual cycle resolves to one level on each side:
# A </#B>
# B </#A><section id="A">
<h1>A <a href="#B">B A </a></h1>
</section>
<section id="B">
<h1>B <a href="#A">A B </a></h1>
</section>A normal (non-cyclic) cross-reference still resolves:
# Intro
See </#Intro>.<section id="Intro">
<h1>Intro</h1>
<p>See <a href="#Intro">Intro</a>.</p>
</section>Only the id hoists to the section wrapper
1 conformance fixture
On a top-level heading the id moves to the <section> and every other attribute stays on the <h*> - identically whether the id was slugged from the heading text or written as {#id}. Worth pinning because djot resolved the same question the other way (all attributes migrate) and then implemented that resolution only for the explicit-id case, so its two cases disagree (jgm/djot.js#144). Carve's agree, and that is what keeps the rule stable when the wrapper is switched off: the id returns to the <h*> and nothing else moves.
{a=b .c}
# Auto slug
{a=b .c #explicit}
# Written id<section id="Auto-slug">
<h1 a="b" class="c">Auto slug</h1>
</section>
<section id="explicit">
<h1 a="b" class="c">Written id</h1>
</section>Headings inside containers are not wrapped
1 conformance fixture
A <section> models this document's own outline, so only top-level headings open one. A heading inside a blockquote, div, or list item emits a bare <h*> with its id on the heading itself. The ids are still assigned, still share the one document-order dedup namespace with top-level headings, and are still </#id> crossref targets - only the wrapper and the id's emission site differ.
> # Quoted
>
> Quoted body.
:::
# Divved
:::
- # In an item
Item body.<blockquote>
<h1 id="Quoted">Quoted</h1>
<p>Quoted body.</p>
</blockquote>
<div>
<h1 id="Divved">Divved</h1>
</div>
<ul>
<li>
<h1 id="In-an-item">In an item</h1>
<p>Item body.</p>
</li>
</ul>Attribute order on an unwrapped heading
1 conformance fixture
A heading that carries no <section> wrapper emits its id on the <h*>, which puts a generated attribute next to authored ones. The author's order is never rearranged; the engine-minted id joins at the end. An id the author wrote is not generated, so it keeps its authored position instead.
Worth pinning because the combination was previously unreachable except through a container, and no case gave such a heading attributes - so all three engines picked different answers here and every one of them stayed green (PART 10 §1).
> {a=b .c}
> # Auto
> {#x a=b}
> # Written
:::
{a=b .c}
# Divved
:::<blockquote>
<h1 a="b" class="c" id="Auto">Auto</h1>
</blockquote>
<blockquote>
<h1 id="x" a="b">Written</h1>
</blockquote>
<div>
<h1 a="b" class="c" id="Divved">Divved</h1>
</div>Implicit heading references with no definition
1 conformance fixture
A [text][] that matches no link definition falls back to the document's headings by their rendered text (PART 9R R1). The label and the heading text are both trimmed, whitespace-collapsed and NFC-normalized, then compared exactly: case is not folded, so [getting started][] does not reach # Getting Started and stays literal.
A heading under a blockquote is declined - quoted text names the quoted document's headings, not this one's - while a list item resolves, because that is the author's own grouping. An unmatched label stays literal, and a real link definition wins the tie.
Worth pinning because every case that existed paired [X][] with an [X]: url definition, so the fallback branch had no coverage at all and the executable spec had never implemented it (carve#453).
# Getting Started
See [Getting Started][], [getting started][] and [Missing][].
> # Quoted
See [Quoted][].
- # In an item
See [In an item][].
# Defined
[Defined]: /wins
See [Defined][].<section id="Getting-Started">
<h1>Getting Started</h1>
<p>See <a href="#Getting-Started">Getting Started</a>, [getting started][] and [Missing][].</p>
<blockquote>
<h1 id="Quoted">Quoted</h1>
</blockquote>
<p>See [Quoted][].</p>
<ul>
<li>
<h1 id="In-an-item">In an item</h1>
</li>
</ul>
<p>See <a href="#In-an-item">In an item</a>.</p>
</section>
<section id="Defined">
<h1>Defined</h1>
<p>See <a href="/wins">Defined</a>.</p>
</section>Explicit references do not use heading fallback
2 conformance fixtures
An explicit reference needs a link definition. A heading with the same name only resolves the collapsed form (CARVE-P9R-001).
# Plan
See [x][Plan] and [Plan][].<section id="Plan">
<h1>Plan</h1>
<p>See [x][Plan] and <a href="#Plan">Plan</a>.</p>
</section>The same rule holds when the display text differs from the heading. A definition still resolves an explicit label and takes priority for a collapsed reference.
# Plan
[Plan]: /defined
See [x][Missing], [x][Plan] and [Plan][].<section id="Plan">
<h1>Plan</h1>
<p>See [x][Missing], <a href="/defined">x</a> and <a href="/defined">Plan</a>.</p>
</section>A heading id keeps a non-ASCII space
1 conformance fixture
The id is the heading's text with each run of non-alphanumeric ASCII replaced by -; non-ASCII characters pass through unchanged. A no-break space in the text is non-ASCII, so it survives into the id rather than becoming a separator - and the id carries the character itself, not an entity. (The marker's own separator must be an ASCII space: # Title is a paragraph, not a heading.)
# Title<section id=" Title">
<h1> Title</h1>
</section>Paired German quotes leave no quote in a heading id
1 conformance fixture
## 4. Globale und Mandanten-Vorlagen, „2 aktive Templates“<section id="s-4-Globale-und-Mandanten-Vorlagen-2-aktive-Templates">
<h2>4. Globale und Mandanten-Vorlagen, „2 aktive Templates“</h2>
</section>A heading reference folds Unicode normalization, but not compatibility
1 conformance fixture
The heading index is keyed on rendered plain text (PART 9R R1): trimmed, internal whitespace collapsed, NFC-normalized, then compared exactly. NFC has to be in that list because the ID side already normalizes (§25) - without it a document publishes id="Café" and then declines [Café][] against the very heading that produced it, and the two spellings look identical on screen so the miss has no visible cause. The heading below is written Cafe + U+0301 and the reference is precomposed U+00E9.
Compatibility folding is NOT in the list: [file][] does not reach # file. NFKC would change which text the author is quoting rather than how it is spelled. carve-rs folded NFC and the other three did not (carve#725).
# Café
see [Café][] and [file][]
# file<section id="Café">
<h1>Café</h1>
<p>see <a href="#Café">Café</a> and [file][]</p>
</section>
<section id="file">
<h1>file</h1>
</section>A collapsed reference reaches a heading by the heading's rendered text
11 conformance fixtures
275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-2275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-3275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-4275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-5275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-6275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-7275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-8275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-9275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-10275-a-collapsed-reference-reaches-a-heading-by-the-heading-s-rendered-text-11
PART 9R R1's implicit heading fallback keys the index by each heading's RENDERED PLAIN TEXT, so # *bold* heading is registered as bold heading. R1 said the label and the heading text are "both" trimmed, collapsed and NFC-normalized (case-folded too, at the time), but it never said which string the label side contributes - its source run or its rendered plain text. Read as the source run, the asterisks survive all four normalizations and no heading containing markup is reachable by its collapsed spelling; read as rendered plain text, it is. Nothing pinned either answer, and carve-js took the first reading while carve-rs, carve-php and the executable spec took the second (markup-carve/carve#648).
It is settled as rendered plain text on this path: the heading side of the comparison is already rendered plain text, and two strings of different kinds can never meet.
# *bold* heading
[*bold* heading][]<section id="bold-heading">
<h1><strong>bold</strong> heading</h1>
<p><a href="#bold-heading"><strong>bold</strong> heading</a></p>
</section>A code span in the heading is the same row, and worth pinning separately because an implementation that strips a fixed list of emphasis characters can pass the first one and fail this one:
# `code()` heading
[`code()` heading][]<section id="code-heading">
<h1><code>code()</code> heading</h1>
<p><a href="#code-heading"><code>code()</code> heading</a></p>
</section>Those two were the whole sample for a long time, and both are on the list a character-class strip would carry, so the list itself went unmeasured. These are the shapes such a strip cannot reach (markup-carve/carve#1011). Carve's emphasis delimiter is /, and no strip can remove it without eating every path and URL an author might quote:
# an /em/ heading
[an /em/ heading][]<section id="an-em-heading">
<h1>an <em>em</em> heading</h1>
<p><a href="#an-em-heading">an <em>em</em> heading</a></p>
</section>An ESCAPE is the shape where the two sides meet at neither spelling: the heading renders a_b, the label as written is a\_b, and deleting the underscore from the label leaves the backslash behind.
# a\_b heading
[a\_b heading][]<section id="a-b-heading">
<h1>a_b heading</h1>
<p><a href="#a-b-heading">a_b heading</a></p>
</section>A NESTED LINK in the label contributes its text and not its destination, which is the heading side's own rule; dropping the brackets alone leaves (/y) standing. The resolved reference carries no nested anchor, because links never nest (PART 12 §3a).
# a [x](/y) b
[a [x](/y) b][]<section id="a-x-b">
<h1>a <a href="/y">x</a> b</h1>
<p><a href="#a-x-b">a x b</a></p>
</section>SMART TYPOGRAPHY is the shape with no markup characters in it at all: the heading holds the curly apostrophe the substitution produced and the label holds the one the author typed, so only a comparison made after rendering relates them.
# it's a heading
[it's a heading][]<section id="it-s-a-heading">
<h1>it’s a heading</h1>
<p><a href="#it-s-a-heading">it’s a heading</a></p>
</section>An INLINE LITERAL contributes its content, the same as the code span above (§27 renders it as visible prose):
# a !`Cat` b
[a !`Cat` b][]<section id="a-Cat-b">
<h1>a Cat b</h1>
<p><a href="#a-Cat-b">a Cat b</a></p>
</section>A SYMBOL SHORTCODE is the one shape where the two sides meet by both contributing NOTHING. The slug rule (syntax.md §4.1 step 1) takes the heading's rendered plain text "inline markup removed; symbols :name: and footnote references excluded", so # a :smile: b is a-b and is keyed a b. The exclusion is by CONSTRUCT and not by what the symbol renders as, which is what makes the id hold still: a symbol resolves through processor configuration - an inline-renderer handler, else the renderer's symbols map, else the literal :name: - while an id is assigned in a parse pass no renderer option reaches. An id keyed on the shortcode NAME would name a spelling the document stops rendering the moment a host configures a map, and one keyed on the RESOLVED value would move every such id at that same moment. The corpus renders with no map, so the heading below prints :smile: and is still a-b.
# a :smile: b
[a :smile: b][]<section id="a-b">
<h1>a :smile: b</h1>
<p><a href="#a-b">a :smile: b</a></p>
</section>The exclusion reaches the INDEX KEY as well, and it has to: the index is keyed by the same rendered plain text, so a heading that excludes the shortcode is keyed a b and is reachable by that spelling too. Excluding it from the id alone would leave the id and the key describing two different strings.
# a :smile: b
[a b][]<section id="a-b">
<h1>a :smile: b</h1>
<p><a href="#a-b">a b</a></p>
</section>The two exclusions compose: a heading holding both a symbol and emphasis contributes the emphasis text and not the shortcode.
# a :smile: /b/ c
[a :smile: /b/ c][]<section id="a-b-c">
<h1>a :smile: <em>b</em> c</h1>
<p><a href="#a-b-c">a :smile: <em>b</em> c</a></p>
</section>The strip is SCOPED TO THE HEADING INDEX. An authored definition is still matched by the label as written - 193-a-collapsed-reference-is-matched-by-the-label-the-author-wrote pins both directions of that, and a change that reaches it is a deviation from R1 rather than a generalization of it. The tie-break is unaffected too: linkDefs wins, so a definition whose label carries the same markup beats the heading the fallback would otherwise find.
[*bold* heading]: /x
# *bold* heading
[*bold* heading][]<section id="bold-heading">
<h1><strong>bold</strong> heading</h1>
<p><a href="/x"><strong>bold</strong> heading</a></p>
</section>Heading-index plain text covers visible leaves and rejects an empty key
4 conformance fixtures
288-heading-index-plain-text-covers-visible-leaves-and-rejects-an-empty-key288-heading-index-plain-text-covers-visible-leaves-and-rejects-an-empty-key-2288-heading-index-plain-text-covers-visible-leaves-and-rejects-an-empty-key-3288-heading-index-plain-text-covers-visible-leaves-and-rejects-an-empty-key-4
The heading index uses the same rendered-plain-text projection on both sides. Autolink display text and image alternative text are visible leaves and remain; symbols and footnote references are the named exclusions. Resolving the outer link does not flatten a parsed non-link tag span. When all content is excluded, the heading still receives the fallback id s, but no empty index key exists.
# a <https://e.com> b
[a <https://e.com> b][]<section id="a-https-e-com-b">
<h1>a <a href="https://e.com">https://e.com</a> b</h1>
<p><a href="#a-https-e-com-b">a https://e.com b</a></p>
</section># a  b
[a  b][]<section id="a-alt-b">
<h1>a <img src="/i.png" alt="alt"> b</h1>
<p><a href="#a-alt-b">a <img src="/i.png" alt="alt"> b</a></p>
</section># a A b
[a A b][]<section id="a-65-b">
<h1>a &#65; b</h1>
<p><a href="#a-65-b">a &#65; b</a></p>
</section># :smile:
[:smile:][]<section id="s">
<h1>:smile:</h1>
<p>[:smile:][]</p>
</section>A heading comment preserves code-span content
8 conformance fixtures
516-a-heading-comment-preserves-code-span-content516-a-heading-comment-preserves-code-span-content-2516-a-heading-comment-preserves-code-span-content-3516-a-heading-comment-preserves-code-span-content-4516-a-heading-comment-preserves-code-span-content-5516-a-heading-comment-preserves-code-span-content-6516-a-heading-comment-preserves-code-span-content-7516-a-heading-comment-preserves-code-span-content-8
CARVE-P9-041 excludes code spans and raw inline from trailing comment recognition. The heading reads those spans before looking for an outside %%, so their content and the text after them survive. The heading id is derived from the preserved rendered text.
The final two cases recognize a comment at the start of the heading's text and keep a tab followed by %% as content (CARVE-P9-041, carve#3013).
# a `x %% b` c<section id="a-x-b-c">
<h1>a <code>x %% b</code> c</h1>
</section># a ``x ` %% b`` c<section id="a-x-b-c">
<h1>a <code>x ` %% b</code> c</h1>
</section>{#raw-heading}
# a `x %% b`{=html} c<section id="raw-heading">
<h1>a x %% b c</h1>
</section># a `x %% b` c %% hidden<section id="a-x-b-c">
<h1>a <code>x %% b</code> c</h1>
</section>> # a `x %% b` c<blockquote>
<h1 id="a-x-b-c">a <code>x %% b</code> c</h1>
</blockquote># a !`x %% b` c<section id="a-x-b-c">
<h1>a x %% b c</h1>
</section># %% hidden<section id="s">
<h1></h1>
</section># a %% hidden<section id="a-hidden">
<h1>a %% hidden</h1>
</section>Which inline content a heading id is derived from
12 conformance fixtures
332-which-inline-content-a-heading-id-is-derived-from332-which-inline-content-a-heading-id-is-derived-from-2332-which-inline-content-a-heading-id-is-derived-from-3332-which-inline-content-a-heading-id-is-derived-from-4332-which-inline-content-a-heading-id-is-derived-from-5332-which-inline-content-a-heading-id-is-derived-from-6332-which-inline-content-a-heading-id-is-derived-from-7332-which-inline-content-a-heading-id-is-derived-from-8332-which-inline-content-a-heading-id-is-derived-from-9332-which-inline-content-a-heading-id-is-derived-from-10332-which-inline-content-a-heading-id-is-derived-from-11332-which-inline-content-a-heading-id-is-derived-from-12
The id comes from the heading's TEXT CONTENT: every inline contributes the literal text it carries, and an inline carrying no text of its own contributes nothing (markup-carve/carve#1283). The section stated what happens to case, to non-ASCII characters, to typography and to a leading digit, and never which content those rules were applied to - which is how one engine could leave math out while keeping the code span beside it.
A math run contributes its text, exactly as the code span below it does. The two are the same shape of node holding the same kind of verbatim text, and no rule can keep one and drop the other - only a list can:
# a $`x` b<section id="a-x-b">
<h1>a <span class="math inline" role="math">\(x\)</span> b</h1>
</section>So a heading that is ONLY math has text, and does not reach the empty-text fallback:
# $`x`<section id="x">
<h1><span class="math inline" role="math">\(x\)</span></h1>
</section>Display math is the same run with a wider delimiter, and contributes the same way:
# a $$`x` b<section id="a-x-b">
<h1>a <span class="math display" role="math">\[x\]</span> b</h1>
</section>The control the ruling turned on: a code span already contributed its text in every engine, and it still does. Its answer is what makes the math answer a rule rather than a preference:
# a `c` b<section id="a-c-b">
<h1>a <code>c</code> b</h1>
</section>An image contributes its ALT TEXT, which is the text it carries:
# a  b<section id="a-alt-b">
<h1>a <img src="i.png" alt="alt"> b</h1>
</section>A link contributes its label, not its destination:
# a [link](/u) b<section id="a-link-b">
<h1>a <a href="/u">link</a> b</h1>
</section>An abbreviation definition written on the heading line is not a definition there at all, so its text is heading text, verbatim:
# a *[HTML]: x b<section id="a-HTML-x-b">
<h1>a *[HTML]: x b</h1>
</section>A superscript contributes its content, like every other inline that wraps text:
# a {^up^} b<section id="a-up-b">
<h1>a <sup>up</sup> b</h1>
</section>The other half of the rule. An inline footnote carries no text of its own - the body belongs to the note, not to the heading - so it contributes nothing, and the marker it renders as contributes nothing either:
# a ^[note] b<section id="a-b">
<h1>a <a id="fnref1" href="#fn1" role="doc-noteref"><sup>1</sup></a> b</h1>
</section>
<section role="doc-endnotes" aria-label="Footnotes">
<hr>
<ol>
<li id="fn1">
<p>note<a href="#fnref1" role="doc-backlink" aria-label="Back to reference">↩</a></p>
</li>
</ol>
</section>A cross-reference contributes nothing even when it RESOLVES and renders the target's text. This is where "the construct, not the output" is load-bearing: the id is assigned before the reference is resolved, so the rule cannot depend on what the link ends up saying:
## Target
# a </#Target> b<section id="Target">
<h2>Target</h2>
</section>
<section id="a-b">
<h1>a <a href="#Target">Target</a> b</h1>
</section>A symbol shortcode contributes nothing for the same reason, read from the other side: a symbol resolves through processor configuration, and with no map it renders as its own literal text - which is still not heading text:
# a :smile: b<section id="a-b">
<h1>a :smile: b</h1>
</section>And a line comment contributes nothing by ending the line: everything after it is comment, so the id is derived from what is left:
# a %% c<section id="a">
<h1>a</h1>
</section>Two shapes are deliberately NOT settled by the list above, because the engines still disagree about them and no ruling covers either. An EDITORIAL COMMENT ({# … #}) carries literal text and renders it inside a critic-comment span, and a RAW INLINE (`…`{=html}) carries a payload that is emitted verbatim: measured on carve-js 620def4e and the executable spec, # a {# hidden #} b gives a-b in the engine and a-hidden-b in the oracle, and the raw inline splits the same way. Both are named here rather than pinned so the sentence in Heading IDs is not read as having answered them.
An editorial comment contributes nothing to a heading id
3 conformance fixtures
An editorial comment is about the text, not part of it, so it never moves a heading id. The heading index and a task box name read the same text.
# x {#c#} y
[x y][]<section id="x-y">
<h1>x <span class="critic-comment">c</span> y</h1>
<p><a href="#x-y">x y</a></p>
</section>- [ ] x {#c#} y
- [x] {# note #}done<ul class="task-list">
<li><input type="checkbox" disabled aria-label="x y"> x <span class="critic-comment">c</span> y</li>
<li data-task-state="x"><input type="checkbox" checked disabled aria-label="done"> <span class="critic-comment"> note </span>done</li>
</ul># Plan {#draft#}
# Plan<section id="Plan">
<h1>Plan <span class="critic-comment">draft</span></h1>
</section>
<section id="Plan-2">
<h1>Plan</h1>
</section>Raw inline content in heading ids
2 conformance fixtures
Raw inline content contributes no heading id text, even when the target is HTML:
# a `<b>x</b>`{=html} c<section id="a-c">
<h1>a <b>x</b> c</h1>
</section>A heading made only of raw inline content uses the empty id fallback:
# `<b>x</b>`{=html}<section id="s">
<h1><b>x</b></h1>
</section>Headings
2 conformance fixtures
A # at line start without a following space is a tag, not a heading. By default it renders as a styled inline token, not an invented link target.
#notaheading<p><span class="tag"><strong>#notaheading</strong></span></p>A heading that skips an intermediate level still nests by section: # H1 followed by ### H3 places H3's <section> inside H1's, and Carve does not synthesize an intervening <h2>/<section> (§13 — the stack closes only sections at level >= N).
# H1
### H3
content<section id="H1">
<h1>H1</h1>
<section id="H3">
<h3>H3</h3>
<p>content</p>
</section>
</section>Numbered cross-references
3 conformance fixtures
A #word stays a tag, never a number placeholder.

^ See #data for details<figure>
<img src="c.jpg" alt="chart">
<figcaption>See <span class="tag"><strong>#data</strong></span> for details</figcaption>
</figure>An escaped \# is a literal number sign, never a placeholder.

^ Costs \# units<figure>
<img src="p.jpg" alt="price">
<figcaption>Costs # units</figcaption>
</figure>A # inside inline markup is literal. Write the markup around the label and leave the placeholder outside it.

^ a *# x* b<figure>
<img src="a.jpg" alt="a">
<figcaption>a <strong># x</strong> b</figcaption>
</figure>Heading IDs
3 conformance fixtures
Smart-typography substitutions (curly quotes, dashes, ellipsis, arrows, and the like) are reversed to their ASCII source before the id is computed, so an id never depends on presentational typography.
# Don't repeat yourself
# Step 1 -> done...<section id="Don-t-repeat-yourself">
<h1>Don’t repeat yourself</h1>
</section>
<section id="Step-1-done">
<h1>Step 1 -> done…</h1>
</section>A slug that begins with any Unicode number (Arabic-Indic digits, superscripts, Roman numerals) is prefixed with s-, because a leading digit is a valid HTML id but not a bare CSS selector.
# ١٢٣ heading
# ²super
# Ⅷ chapter<section id="s-١٢٣-heading">
<h1>١٢٣ heading</h1>
</section>
<section id="s-²super">
<h1>²super</h1>
</section>
<section id="s-Ⅷ-chapter">
<h1>Ⅷ chapter</h1>
</section>A heading whose text yields no identifier characters falls back to s.
# ( )<section id="s">
<h1>( )</h1>
</section>Empty heading slugs use the ordinary duplicate suffix
1 conformance fixture
An empty heading slug starts at s; another empty slug receives the next available duplicate suffix.
# ( )
# ( )<section id="s">
<h1>( )</h1>
</section>
<section id="s-2">
<h1>( )</h1>
</section>A cross-reference clones heading inline nodes
1 conformance fixture
A cross-reference carries the target heading's inline markup into its link label.
# *Setup*
See </#Setup>.<section id="Setup">
<h1><strong>Setup</strong></h1>
<p>See <a href="#Setup"><strong>Setup</strong></a>.</p>
</section>A heading slug that starts with any Unicode number takes the s- prefix
2 conformance fixtures
A generated heading id whose first character is of general category N, not only an ASCII digit, is prefixed s- (CARVE-P2-004, carve#4157).
# ²super
# ١٢٣ heading<section id="s-²super">
<h1>²super</h1>
</section>
<section id="s-١٢٣-heading">
<h1>١٢٣ heading</h1>
</section># 1st
# x²<section id="s-1st">
<h1>1st</h1>
</section>
<section id="x²">
<h1>x²</h1>
</section>A heading id reverses every double arrow
3 conformance fixtures
A heading id reverses smart typography to its ASCII source before slugging (CARVE-P2-004, carve#4293). ⇐ reverses to <== and ⇔ to <=>, like ⇒ to ==>, so the arrow collapses into the separator and no glyph reaches the id.
# a <== b<section id="a-b">
<h1>a ⇐ b</h1>
</section># a <=> b<section id="a-b">
<h1>a ⇔ b</h1>
</section># x <==b and y<=>z<section id="x-b-and-y-z">
<h1>x ⇐b and y⇔z</h1>
</section>An id dropped with an unresolved reference reserves nothing
2 conformance fixtures
An unresolved reference keeps its trailing attribute run as text (PART 9R, carve#4816), so its {#i} is no id. Heading-id dedup counts only ids the document renders (CARVE-P2-004), and the heading below keeps id="i" (carve#4288).
x[^n]{#i}
## {#i}<p>x[^n]{#i}</p>
<section id="i">
<h2>{<span class="tag"><strong>#i</strong></span>}</h2>
</section>An automatic slug reads the same way.
x[^n]{#i}
## i<p>x[^n]{#i}</p>
<section id="i">
<h2>i</h2>
</section>An indented dash line neither opens nor closes frontmatter
2 conformance fixtures
PART 1 frontmatter_open and frontmatter_close admit no indent (carve#4453). When a first-line opener has no unindented closer, it consumes through the document end (carve#5016).
---
a
---
x<hr>
<p>a</p>
<hr>
<p>x</p>---
a
---
xA cross-reference to a repeated explicit id finds the first
2 conformance fixtures
PART 9R R4 and CARVE-P2-004 (carve#4450). Both headings keep the id as written.
{#x}
# A
{#x}
# B
</#x><section id="x">
<h1>A</h1>
</section>
<section id="x">
<h1>B</h1>
<p><a href="#x">A</a></p>
</section>> {#x}
> # A
{#x}
# B
</#x><blockquote>
<h1 id="x">A</h1>
</blockquote>
<section id="x">
<h1>B</h1>
<p><a href="#x">A</a></p>
</section>A cloned heading drops its ids
2 conformance fixtures
A cross-reference's link text clones the heading's inline nodes, and the clone drops every id, so no id appears twice in the document (markup-carve/carve#4554).
# *A*{#z}
</#A><section id="A">
<h1><strong id="z">A</strong></h1>
<p><a href="#A"><strong>A</strong></a></p>
</section>Ids drop at every depth, and every other attribute stays on its own element.
# *[b]{#y abbr="T"}*{#z}
</#b><section id="b">
<h1><strong id="z"><abbr title="T" id="y">b</abbr></strong></h1>
<p><a href="#b"><strong><abbr title="T">b</abbr></strong></a></p>
</section>DEL is ASCII nonalphanumeric for heading slugs
1 conformance fixture
An automatic heading id replaces DEL (U+007F) and an adjacent punctuation run with one hyphen (PART 2, CARVE-P2-004, carve#5462).
# ab
# a!?b<section id="a-b">
<h1>ab</h1>
</section>
<section id="a-b-2">
<h1>a!?b</h1>
</section>A terminal heading hard break keeps its implicit reference
2 conformance fixtures
PART 2 CARVE-P2-004 and PART 9R R1 key a heading's implicit reference by its rendered plain text. A hard break at the end writes <br> and a serialization newline in HTML, but contributes no text to that key (carve#5659).
# [g][]\<section id="g">
<h1><a href="#g">g</a><br>
</h1>
</section>The same key is available to a reference after the heading.
# g\
[g][]<section id="g">
<h1>g<br>
</h1>
<p><a href="#g">g</a></p>
</section>Nested reference labels contribute to heading text
2 conformance fixtures
PART 2 CARVE-P2-004 derives a heading id from the text that each inline carries, before reference resolution. A reference label can itself hold another reference label; every level contributes its text (carve#5664).
# a [[x][]][]<section id="a-x">
<h1>a [[x][]][]</h1>
</section>With no surrounding text, the generated id also resolves the outer collapsed reference through the heading index (PART 9R R1).
# [[x][]][]<section id="x">
<h1><a href="#x">x</a></h1>
</section>