Finding your way through a long document / Back-of-book index
An index with page references that stay correct after an edit
An alphabetical list of subjects with the pages they appear on, at the end of a long reference document.
Why this block is harder than it looks
An index is a contents page with two extra problems. The entries are subjects rather than headings, so they are not derivable from the document structure and have to be marked in the text. And each entry can point at several pages, which means several target-counter resolutions in one entry, printed as a comma-separated run that has to stay readable when it grows to six numbers. On top of that an index is set in two or three narrow columns, so the entries wrap constantly and need a hanging indent that survives a column break.
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.
- Mark index targets in the text with anchors, and generate the entries from those anchors rather than typing page numbers.
- Resolve every reference with target-counter, so an edit anywhere renumbers the whole index.
- Set the numbers in tabular figures and separate them with a comma and a thin space, so a run of six is scannable.
- Use a hanging indent inside narrow columns so continuation lines are visibly subordinate to the entry.
- Use CSS columns, not a grid, so the alphabetical run reads down each column before moving across.
- Sub-entries indented one level and no deeper. A three-level index in a two-column layout leaves about fifteen characters per line.
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.
<section class="index">
<h2>Index</h2>
<ul>
<li>Access limitations
<a href="#access-1">p</a><a href="#access-2">p</a></li>
<li>Damp
<ul>
<li>rising <a href="#damp-rising">p</a></li>
<li>penetrating <a href="#damp-pen">p</a></li>
</ul>
</li>
</ul>
</section>
<style>
.index ul { list-style: none; margin: 0; padding: 0; }
.index > ul {
columns: 2;
column-gap: 10mm;
column-fill: auto; /* reads down, then across */
font-size: 8.5pt;
}
.index > ul > li {
break-inside: avoid;
padding-left: 5mm;
text-indent: -5mm; /* hanging indent for wrapped entries */
margin-bottom: 1.5pt;
}
.index ul ul li { padding-left: 8mm; text-indent: -3mm; }
.index a { text-decoration: none; color: inherit; font-size: 0; }
.index a::after {
content: target-counter(attr(href url), page);
font-size: 8.5pt;
font-variant-numeric: tabular-nums;
}
.index a + a::before { content: ", "; font-size: 8.5pt; }
</style>What breaks when it is built the obvious way
Typing the page numbers. An index is the block most sensitive to any edit anywhere in the document, and hand-typed references are wrong after the first change and stay wrong, because nothing about a wrong page number is visible without following it.
How to prove it survived pagination
Insert a page in the middle of the document and render again. Every index reference after the insertion should have moved by one. Then read down the first column and confirm it runs A to M rather than A, B, C across.
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 product datasheet 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.
A summary box at the head of a section that stays with it
Two or three lines at the start of a long section saying what it concludes, so a reader can decide whether to read the rest.
A cover page with its own margins and no header or footer
The first page of a long document, which usually wants different margins, no running header and no page number, and therefore needs its own page rule.
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.
A full page image that reaches the paper edge on all four sides
An image occupying an entire page with no margin, used as a divider, a cover or a plate in a document that will be trimmed.
Product datasheet, as a complete file
The whole document with this block already in place, ready to copy and change.
column-count 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.