Finding your way through a long document / Attachments list
An attachments list that says what is attached and where it is
A list of documents that accompany this one, with enough identification that a reader can tell whether they have received everything.
Why this block is harder than it looks
The list exists so a recipient can check a set is complete, which means every entry needs to be identifiable without opening it: a title, a reference and, where the attachment is bound in, a page. If the attachments are separate files rather than pages, the page column is meaningless and printing it empty is worse than omitting it. There is also an ordering question that people get wrong: the list should be in the order the attachments are presented, not alphabetical, because a reader checking a stack works through it in order.
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.
- Number the entries and match the numbering to whatever is marked on the attachments themselves. A list numbered 1 to 6 against attachments labelled A to F helps nobody.
- Include a count at the head or foot. Six attachments listed and a stated total of six lets a reader check completeness in one operation rather than six.
- Give the page reference only when the attachment is bound in, and use target-counter so it stays correct. Where attachments are separate, replace the column with the file reference.
- Order as presented. Alphabetical order is only correct if the attachments are in alphabetical order.
- Keep each entry on one line where possible, and let a long title wrap with a hanging indent so the numbers stay in a column.
- Keep the whole list together with break-inside: avoid unless it is long, in which case repeat the heading on continuation with the word continued.
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="attachments">
<h2>Attachments</h2>
<ol>
<li><a href="#att-1">Site plan, drawing WH-2026-014</a></li>
<li><a href="#att-2">Photographic record, 14 images</a></li>
<li><a href="#att-3">Calibration certificate, meter 4471-A</a></li>
</ol>
<p class="count">3 attachments.</p>
</section>
<style>
.attachments { break-inside: avoid; margin-top: 14pt; }
.attachments ol { margin: 6pt 0 0; padding-left: 16pt; }
.attachments li {
break-inside: avoid;
margin-bottom: 3pt;
font-size: 9.5pt;
}
.attachments a { text-decoration: none; color: inherit; }
/* page reference, resolved after pagination, only for bound attachments */
.attachments a::after {
content: leader(". ") target-counter(attr(href url), page);
font-variant-numeric: tabular-nums;
color: #555;
}
.attachments .count { margin-top: 6pt; font-size: 8.5pt; color: #555; }
</style>What breaks when it is built the obvious way
Printing a page column for attachments that are separate files. The column resolves to nothing, every row shows a blank where a number should be, and a reader reasonably concludes the attachments are missing from the document rather than delivered alongside it.
How to prove it survived pagination
Render with bound attachments and confirm every page reference resolves to a real page. Then render the separate-file case and confirm no empty page column appears. Finally, count the entries against the stated total, which is the check the block exists to make possible.
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 incident 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.
A glossary with hanging indents that stays scannable
Defined terms with their definitions, set so a reader can find a term by scanning down the left edge.
An abbreviations list in columns that reads down, not across
Short forms with their expansions, usually at the front of a technical document, set compactly because there are often a lot of them.
A document control block with owner, status and review date
Owner, status, issue date, review date and reference, gathered into one block near the front of a controlled document.
A free text notes block that does not overflow or leave a gap
An open area carrying whatever somebody typed into a notes field, which may be empty, may be one line, and may be four pages.
Incident 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.