Numbers, tables and totals / Figure with caption
Keeping an image and its caption on the same page
An image with a numbered caption beneath it, which has to stay with its caption and has to be referable from the text that mentions it.
Why this block is harder than it looks
Two problems that look like one. The first is atomicity: an image and its caption are a single unit, and a page break between them produces a caption with no picture, which is the most obviously broken thing a document can do. The second is that the figure has a number, that number is referred to from the body text, and hand-maintained numbering will eventually be wrong because somebody inserts a figure in the middle. Both are solvable, and the second is where CSS counters earn their place.
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.
- Wrap image and caption in a figure element and put break-inside: avoid on the wrapper, not on the image, or the caption is free to leave.
- Number with a CSS counter rather than in the content, so inserting a figure renumbers everything after it without editing text.
- Constrain the image by height as well as width. An image sized to full width on a portrait page can be taller than the text block, and what the renderer does then is not something to depend on.
- Give the image explicit intrinsic dimensions in the markup so layout does not shift while the image resolves.
- Add break-before: avoid to the caption, for the same reason as the grand-total row: if something has to give, it should give above the figure.
- Keep the caption narrower than the image and set it under the image rather than beside it. A caption running the full text measure under a half-width image does not read as belonging to it.
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.
<figure class="fig">
<img src="site-plan.png" alt="Ground floor plan with survey points marked"
width="1400" height="900">
<figcaption>Survey points, ground floor. Points 4 and 5 were
inaccessible at the time of inspection.</figcaption>
</figure>
<style>
body { counter-reset: figure; }
.fig {
break-inside: avoid; /* image and caption are one unit */
margin: 14pt 0;
text-align: center;
}
.fig img {
max-width: 100%;
max-height: 150mm; /* height, because the page is the limit */
height: auto;
}
.fig figcaption {
counter-increment: figure;
break-before: avoid;
margin: 6pt auto 0;
max-width: 86%;
font-size: 8.5pt;
color: #444;
text-align: left;
}
.fig figcaption::before {
content: "Figure " counter(figure) ". ";
font-weight: 700;
}
</style>What breaks when it is built the obvious way
Sizing the image with a percentage width only. On a page taller than it is wide, a wide image at full width is fine and a tall image at full width overflows the text block. Constrain both dimensions and let the smaller constraint win.
How to prove it survived pagination
Push a figure so it starts within a few lines of the bottom margin, then render. The whole figure should move to the next page and leave white space behind, which is correct. If the image moves and the caption stays, the avoid rule is on the image rather than the wrapper.
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.
Putting a chart in a PDF so it stays sharp and keeps its meaning
A plotted chart placed in the document flow, which has to survive being printed at a size it was not drawn for and in colours that may not be there.
Footnotes in a PDF, and what to do when the page cannot hold them
Notes anchored to a marker in the text and printed at the foot of the page, which is a typesetting feature that renderers have implemented unevenly for years.
Printing an amount in words on a receipt, cheque or contract
The total written out as text as well as digits, which appears on cheques, receipts and contracts because a word cannot be altered with a pen the way a digit can.
A site block with an address, a reference and access notes
Where work is to happen, which is often not a postal address and usually needs a reference, a grid position and a note about getting in.
Multi-page report, as a complete file
The whole document with this block already in place, ready to copy and change.
break-inside 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.