Marks on the page / Photo evidence grid
A photo grid with captions that keeps images the same size
A grid of photographs with numbered captions, used in surveys, inspections and incident reports where the images are the evidence.
Why this block is harder than it looks
Photographs arrive in mixed orientations and mixed aspect ratios, and a grid built by letting each image size itself produces a ragged mess where the eye cannot compare one to another. Forcing them all to one size distorts them, which in an evidence document is not acceptable. The correct answer is a fixed cell with the image fitted inside it, which keeps the grid regular and the images undistorted at the cost of some white space. On top of that, each image needs a number that the body text refers to, and the image and its caption must not be separated by a page 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.
- Give every cell the same fixed height and fit the image inside it with object-fit: contain, so aspect ratios are preserved and the grid stays regular.
- Never use object-fit: cover on evidence photographs. Cropping to fill a cell removes part of the evidence, which is the one thing this document cannot do.
- Number with a CSS counter and refer to the numbers from the body text, the same as any figure.
- Keep each image and its caption in one break-inside: avoid cell, and let the grid break between rows.
- Set the caption to a fixed number of lines or allow it to grow the row uniformly, so one long caption does not make one cell taller than its neighbours.
- Give every image an alt description. In an evidence document the description is part of the record, not an accessibility afterthought.
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.
<div class="photos">
<figure>
<img src="p1.jpg" alt="Crack in the rear elevation, 400mm vertical"
width="1600" height="1200">
<figcaption>Rear elevation, vertical crack above the lintel.</figcaption>
</figure>
<figure>
<img src="p2.jpg" alt="Damp staining at the base of the north wall"
width="1200" height="1600">
<figcaption>North wall, staining at floor level.</figcaption>
</figure>
</div>
<style>
body { counter-reset: photo; }
.photos {
display: grid;
grid-template-columns: 1fr 1fr;
gap: 8mm;
margin: 12pt 0;
}
.photos figure {
break-inside: avoid; /* image and caption travel together */
margin: 0;
}
.photos img {
display: block;
width: 100%;
height: 60mm; /* fixed cell, so the grid stays regular */
object-fit: contain; /* never cover: cropping removes evidence */
background: #f2f0ea;
}
.photos figcaption {
counter-increment: photo;
break-before: avoid;
margin-top: 4pt;
font-size: 8pt;
color: #444;
}
.photos figcaption::before {
content: "Photo " counter(photo) ". ";
font-weight: 700;
}
</style>What breaks when it is built the obvious way
Letting the images size themselves. Portrait and landscape photographs in the same grid then produce rows of different heights, the captions stop lining up, and comparing two images against each other becomes guesswork because they are at different scales.
How to prove it survived pagination
Render a grid mixing portrait and landscape images, including one very wide panorama. Every cell should be the same height with the images fitted inside, and nothing should be cropped. Then push a row near a page boundary and confirm no caption is separated from its image.
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 printed checkbox list with boxes big enough to tick by hand
A list of items each with a box to be ticked, used on inspection sheets, handover forms and anything filled in on paper.
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.
A callout box that survives a page break and a monochrome printer
A boxed note set apart from the body text, carrying a warning, a definition or an aside.
Carried forward and brought forward totals on a long table
The running figure printed at the foot of each page and repeated at the top of the next, so a multi-page table can be checked page by page instead of only at the end.
Incident report, as a complete file
The whole document with this block already in place, ready to copy and change.
image-rendering 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.