Finding your way through a long document / Table of contents
A table of contents with page numbers and leader dots
A list of headings with the page each one starts on, which cannot be written by hand because the page numbers do not exist until the document has been laid out.
Why this block is harder than it looks
A contents page needs a number that is only known after pagination, and the pagination depends on how long the contents page is, which depends on how many entries it has. That circularity is why generating one by hand is hopeless in anything that changes. Paged CSS solves it directly with target-counter, which reads the page number of whatever a link points at. The support for it is the thing to check rather than assume, and the leader dots between the title and the number are a second, smaller problem that has a clean answer and several dirty ones.
The decisions that make it work
Reasons rather than a description of the code. Each of these is a choice that has a wrong answer, and the wrong answer is usually the default.
- Build the entries as real links to element ids, then let target-counter resolve the page numbers. Nothing else can be correct after an edit.
- Use the leader() function for the dots where it is supported. Filling the gap with a repeated character or a background image both go wrong at the ends of the line.
- Give every heading a stable id generated from the same source as the entry, so the two cannot drift.
- Right-align the page numbers in their own column with tabular figures, so a three-digit number does not shift the column.
- Indent by heading level and keep at most three levels. A contents listing four levels deep is a document map rather than a way to find something.
- Verify the output rather than trusting the mechanism. If target-counter resolves to nothing, every entry shows a blank or a zero, and that is very easy to ship because it is uniform.
The fragment
Markup and the CSS it needs, and nothing else. It expects a document that already has a page rule and a base stylesheet, so paste it into one rather than opening it on its own.
<nav class="toc">
<h2>Contents</h2>
<ol>
<li class="l1"><a href="#scope">Scope of inspection</a></li>
<li class="l2"><a href="#access">Access limitations</a></li>
<li class="l1"><a href="#findings">Findings</a></li>
</ol>
</nav>
<style>
.toc ol { list-style: none; margin: 0; padding: 0; }
.toc li { break-inside: avoid; margin: 3pt 0; }
.toc .l2 { padding-left: 8mm; font-size: 9.5pt; }
.toc a {
text-decoration: none;
color: inherit;
display: block;
}
/* dots, then the page the target actually landed on */
.toc a::after {
content: leader(". ") target-counter(attr(href url), page);
font-variant-numeric: tabular-nums;
}
</style>What breaks when it is built the obvious way
Writing the page numbers into the markup because the document is short and stable. It is not stable: somebody adds two paragraphs to section two and every number below it is wrong, and a wrong contents page is worse than none because it is trusted.
How to prove it survived pagination
Render, then add a page of content in the middle of the document and render again. Every number after the insertion should have increased. If the numbers are all blank, target-counter did not resolve and the whole mechanism is inert rather than partly working.
Where it sits in a finished document
This page is one block. The document it belongs to has a page rule, a base stylesheet, a header and everything else around it, and repeating all of that here would make thirty pages that say the same thing. The multi-page report template is a complete file with this block already in it, so take that and change the fragment rather than assembling one from parts. The property doing most of the work here is covered on its own page, with the support caveats that belong there rather than here.
Frequently asked
Will this fragment work on its own?
Not as a whole document. It has no page rule, no margins and no base type, because those belong to the document rather than to the block, and duplicating them in every fragment would mean thirty copies to keep in step. Paste it into a template that already has them.
Why does it look right in a browser and wrong in the PDF?
Because a browser window is one continuous surface and a document is a stack of fixed rectangles. Nothing in a scrolling view exercises a page boundary, so every break rule in the fragment is inert until the content is paginated. Render the real thing with enough content to cross two or three boundaries, then look.
Do I need a special option on the render request for this?
No. Everything on this page is CSS and markup, which is your side of the boundary. What the render has to give you is a real page size with real margins, and after that the layout is decided by the stylesheet.
Other parts of a document
The blocks that sit next to this one, and one from the next group along so you are not sealed inside a single kind of problem.
Page 3 of 12 in a footer, on every page but the cover
The folio, printed in a page margin box, usually as a number and a total, and usually required to be absent from the first page.
A running header that shows the current section on every page
A line at the top of each page carrying the document title and, ideally, the section the reader is currently inside.
An appendix with its own numbering that starts on a fresh page
Supporting material at the end of a document, numbered separately from the body so it can be added to without renumbering anything.
A letterhead on the first page only, with the rest indented under it
The organisation's name, mark and address at the head of a document, usually on the first page only, with the body starting below it.
Multi-page report, as a complete file
The whole document with this block already in place, ready to copy and change.
counter(page) in paged output
The property carrying the weight here, with its real support status.
Every part of a document
The full list, grouped by the kind of problem the block poses.
Paste the fragment into the playground inside a page rule and see what it does at a real page size. That is the only way any of this gets confirmed.