Numbering
Headings, figures, cross-references, and footnotes that keep their numbers across every page.
A long document leans on numbers to keep a reader in place: Section 2.1, Figure 3, "see page 7", a footnote mark and the note it points to. Those numbers have to stay fixed as content reflows across pages. Numbering settles them once, in reading order, before the document is divided into pages, then writes each number into the text as plain content. When a paragraph breaks across a page, its number travels with the half it belongs to, so nothing renumbers at a page boundary.
The constructs below opt a document into that pass. <Numbering> configures it, <Counter> reads and advances a named count, <Ref> prints a number computed elsewhere, <TableOfContents> lists the headings, and <Footnote> moves a note to the foot of its page.
Number the headings
Add a <Numbering> element to the document. With no rules inside, it numbers headings h1 through h6 hierarchically: an h1 reads 1, the next h2 under it reads 1.1, an h3 under that reads 1.1.1, and each level restarts the levels beneath it.
The number is prepended to each heading as plain text, so it prints, copies, and exports with the rest of the heading.
To leave a heading out, mark it data-unnumbered. It keeps its place but takes no number, and no table of contents collects it, which suits a preface or an appendix that should not count as a numbered section.
Count figures, tables, and steps
A <Counter> advances a named count where it sits and prints the value. Counters share state by name across the whole document, so every <Counter name="figure" /> continues the same sequence wherever it appears. Naming it is all it takes: there's nothing to declare first, and the count starts at 1.
<figcaption>Figure <Counter name="figure" />: the numbering pass</figcaption>By default a Counter advances the count and shows the new value. The peek prop shows the current value without advancing it, set jumps to an exact value, and reset starts the sequence over. To advance by more than one, pass by. Give a Counter an id to make its printed value a cross-reference target.
Cross-reference a number
A <Ref> prints a number Format already computed for another element, named by its id. Point to a numbered heading to print its section number, or to a Counter's id to print the value that Counter showed.
<h2 id="method">Method</h2>
{/* ...later... */}
<p>The method in Section <Ref to="method" /> settles every number first.</p>References resolve before the document is divided into pages, so a forward reference reads the same as a backward one. Add the page prop to print the page the target landed on instead of its number; that value is filled in once pages are settled.
<p>See the chart on page <Ref to="fig-flow" page />.</p>Customize the scheme
For anything past the default heading scheme, add <NumberingRule> children to <Numbering>. A rule pairs a CSS selector with a counter operation and applies it to every match in document order.
<Numbering>
<NumberingRule match="figure" counter="figure" format="Figure {figure}: " />
</Numbering>This numbers every <figure> and inserts "Figure 1: ", "Figure 2: ", and so on. The format prop holds the text to insert, with {counter} placeholders; a placeholder can carry a style after a colon, as in {chapter:upper-roman}. Other props set the step (increment), set an exact value (set), choose the counter style (counterStyle), and place the number before or after the match (insert).
A rule or <CounterDef> that numbers a heading takes the whole heading scheme
over, so keep rules for h1 through h6 among your own if you replace it.
Config that only adds a non-heading counter, like the figure rule above, leaves
the default heading numbers in place.
Restart a counter under another
To make one counter restart whenever another changes, declare it with a <CounterDef> and name its owner in resetEach. A figure counter that restarts under chapter reads 1.1, 1.2, then 2.1 at the next chapter. Restarts cascade, so a new chapter also zeroes a section counter beneath it.
<Numbering>
<CounterDef name="figure" resetEach="chapter" />
<NumberingRule match="h1" counter="chapter" format="Chapter {chapter}. " />
<NumberingRule match="figure" counter="figure" format="Figure {chapter}.{figure}: " />
</Numbering>Nested lists
To number a list inside a list as 1, 1.1, 1.1.1, mark each list with data-scope and read the open chain with a Counter's join. A data-scope opens a fresh level of its named counter for the list it sits on and closes it when that list ends, so the one counter nests into itself to any depth.
<ol data-scope="item">
<li><Counter name="item" join="." /> First
<ol data-scope="item">
<li><Counter name="item" join="." /> Nested</li> {/* 1.1 */}
</ol>
</li>
<li><Counter name="item" join="." /> Second</li> {/* 2 */}
</ol>When no element exists to carry the mark, wrap the content in a <Scope counter="item">, which leaves no box of its own.
Counter styles
Every number is decimal by default. Set a document-wide default on <Numbering counterStyle="…">, and override it per rule, per <Counter>, per <Ref>, or per <Footnotes>; a placeholder can also carry its own style after a colon, as in {chapter:upper-roman}. The supported styles are decimal, decimal-leading-zero, lower-alpha (also lower-latin), upper-alpha (also upper-latin), lower-roman, upper-roman, and lower-greek; a value outside a style's range falls back to decimal. Because each number is written into the text before pages are split, its inline marker and the value it prints always match.
<Numbering counterStyle="lower-roman">
<NumberingRule match="figure" counter="figure" counterStyle="decimal" format="Figure {figure}: " />
</Numbering>Page numbers are the exception. <PageNumber> and <PageCount> are per-page, so they stay CSS-driven: set their style with the counterStyle prop or the --page-counter-style variable on :host, not through <Numbering>.
Footnotes
A <Footnote> holds a note's text where the note is referenced. Format leaves a numbered marker inline and moves the text to a <Footnotes> region; footnotes count continuously through the document.
<p>The result holds<Footnote>under the stated assumptions</Footnote>.</p>Place a <Footnotes> region in the Layout to set where the notes sit. Without one, a footer area is added to each page that carries a note. A <Footnotes> in feed content instead gathers every note above it into an endnotes list.
List the contents
A <TableOfContents> is filled in after the document is laid out, with one entry per heading its collect selector matches. Each entry carries the heading's number, its title, and the page it reached.
<TableOfContents collect="h1, h2">
<h2>Contents</h2>
</TableOfContents>Children are leading content shown once above the entries, which is where a "Contents" heading goes. The entries are flat anchors in a <nav data-type="toc">, each carrying its outline depth as data-depth instead of sitting in a nested list, so a long contents breaks cleanly between entries. Style them through their data-type hooks and the --toc-* custom properties.
What needs a <Numbering> element
Heading numbers come from <Numbering>: the default h1–h6 scheme, or the rules you add. A <Ref> that points at a heading depends on that heading being numbered, so it depends on <Numbering> too.
The other constructs stand on their own. A <Counter> counts, a <Footnote> flows to its footer, a <Ref> reads a Counter's value, and a <TableOfContents> lists titles and pages, all without a <Numbering> element present.