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.
<template data-type="document" data-title="Report" data-lang="en">
<template data-type="numbering"></template>
<template data-type="layout" data-id="page" data-width="793.71px" data-height="1122.52px">
<template data-type="flow">
<h1>Introduction</h1>
<h2>Background</h2>
</template>
</template>
</template>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><figcaption>Figure <Counter name="figure" />: the numbering pass</figcaption><figcaption>Figure <span data-type="counter" data-name="figure" data-action="next"></span>: 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><h2 id="method">Method</h2>
<!-- ...later... -->
<p>The method in Section <Ref to="method" /> settles every number first.</p><h2 id="method">Method</h2>
<!-- ...later... -->
<p>The method in Section <span data-type="ref" data-to="method"></span> 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><p>See the chart on page <Ref to="fig-flow" page />.</p><p>See the chart on page <span data-type="ref" data-to="fig-flow" data-page></span>.</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><Numbering>
<NumberingRule match="figure" counter="figure" format="Figure {figure}: " />
</Numbering><template data-type="numbering">
<template data-type="numbering-rule" data-match="figure" data-counter="figure" data-format="Figure {figure}: "></template>
</template>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).
Rules add to the default heading scheme. Headings keep their default numbers, and the figure rule numbers figures alongside them.
Replace the heading scheme
To number headings your own way, set defaultHeadings to false and write rules for the headings you want numbered. Turning the default scheme off removes both its numbers and its restarts between heading levels. Declare a <CounterDef> for any restart your own scheme needs.
<Numbering defaultHeadings={false}>
<NumberingRule match=".chapter-title" counter="chapter" format="Chapter {chapter}. " />
</Numbering><Numbering :default-headings="false">
<NumberingRule match=".chapter-title" counter="chapter" format="Chapter {chapter}. " />
</Numbering><template data-type="numbering" data-default-headings="false">
<template data-type="numbering-rule" data-match=".chapter-title" data-counter="chapter" data-format="Chapter {chapter}. "></template>
</template>This numbers only the headings with the chapter-title class. Every other heading, such as a cover title or a "Contents" heading, stays unnumbered.
A rule that numbers a heading while the default scheme is on gives that heading
a second number. Format lists the rule in
DocumentSummary.numbering.doubleNumberingRules.
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 defaultHeadings={false}>
<CounterDef name="figure" resetEach="chapter" />
<NumberingRule match="h1" counter="chapter" format="Chapter {chapter}. " />
<NumberingRule match="figure" counter="figure" format="Figure {chapter}.{figure}: " />
</Numbering><Numbering :default-headings="false">
<CounterDef name="figure" reset-each="chapter" />
<NumberingRule match="h1" counter="chapter" format="Chapter {chapter}. " />
<NumberingRule match="figure" counter="figure" format="Figure {chapter}.{figure}: " />
</Numbering><template data-type="numbering" data-default-headings="false">
<template data-type="counter-def" data-name="figure" data-reset-each="chapter"></template>
<template data-type="numbering-rule" data-match="h1" data-counter="chapter" data-format="Chapter {chapter}. "></template>
<template data-type="numbering-rule" data-match="figure" data-counter="figure" data-format="Figure {chapter}.{figure}: "></template>
</template>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><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><ol data-scope="item">
<li><span data-type="counter" data-name="item" data-join="." data-action="next"></span> First
<ol data-scope="item">
<li><span data-type="counter" data-name="item" data-join="." data-action="next"></span> Nested</li> <!-- 1.1 -->
</ol>
</li>
<li><span data-type="counter" data-name="item" data-join="." data-action="next"></span> 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><Numbering counter-style="lower-roman">
<NumberingRule match="figure" counter="figure" counter-style="decimal" format="Figure {figure}: " />
</Numbering><template data-type="numbering" data-counter-style="lower-roman">
<template data-type="numbering-rule" data-match="figure" data-counter="figure" data-counter-style="decimal" data-format="Figure {figure}: "></template>
</template>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
Footnotes count continuously through the document without a Numbering element. They inherit its counterStyle when one is set. A Layout's Footnotes region can override that style or enable per-page restarting.
See the Footnotes and endnotes guide for inline notes, footer placement, numbering, styling, and endnotes.
List the contents
A <TableOfContents> lists headings with links and page numbers. Numbered headings also include their section numbers.
<TableOfContents collect="h1, h2">
<h2>Contents</h2>
</TableOfContents><TableOfContents collect="h1, h2">
<h2>Contents</h2>
</TableOfContents><template data-type="toc" data-collect="h1, h2">
<h2>Contents</h2>
</template>Place it directly in a Flow's stream, before the headings you want to list. See the Table of contents guide for heading selection, chapter contents, and styling.
Add a running head
A <RunningHead> shows the current chapter or section in a page header or footer. By default, it uses the heading's title and number.
<header>
<RunningHead match="h1" show="start" />
<PageNumber />
</header><header>
<RunningHead match="h1" show="start" />
<PageNumber />
</header><header>
<span data-type="running-head" data-match="h1" data-show="start"></span>
<span data-type="page-number"></span>
</header>Use show="start" to show the section active at the top of the page. Use within to pair section and chapter headers. See the RunningHead reference for selection options, short titles, and sizing.
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 features work without <Numbering>. Counters and footnotes keep their own counts, and a <Ref> can read a Counter's value. A <TableOfContents> lists titles and page numbers. A <RunningHead> shows section titles.