Finding your way through a long document / Section summary box
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.
Why this block is harder than it looks
The box is only useful if it is the first thing on the section, which means it must never be separated from the heading above it, and it must never be the last thing on a page with the section body starting on the next. Both are break rules and they pull in opposite directions: keeping the box with the heading pushes both forward, and keeping the box with the body pulls it back. The content problem is that a summary that repeats the section's first paragraph is worse than none, and that is what a summary written after the section usually becomes.
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.
- Bind the heading, the box and the first paragraph of the body into one break-inside: avoid group, so all three move together rather than fighting over the boundary.
- State the conclusion, not the topic. A box saying this section covers drainage tells the reader nothing they did not get from the heading.
- Keep it to about forty words. A longer box is a section of its own and the reader now has two things to read.
- Set it apart with a rule or an indent rather than a filled box, so it does not read as a callout, which carries different information.
- Do not repeat the box's wording in the body. A reader who has just read the summary and then meets the same sentence concludes the document is padded.
- Use one consistently or not at all. Summary boxes on three sections out of eight look like the other five were unfinished.
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="with-summary">
<h2>Drainage</h2>
<p class="summary">The below-ground drainage is serviceable but the gully at
the rear is undersized for the roof area it serves, and it surcharges in
heavy rain.</p>
<p>The system was inspected by camera from the rear manhole ...</p>
</section>
<style>
.with-summary {
break-inside: avoid; /* heading, summary and first para as one */
}
.with-summary h2 { break-after: avoid; margin: 0 0 5pt; }
.with-summary .summary {
margin: 0 0 8pt;
padding-left: 6mm;
border-left: 2pt solid #999; /* a rule, not a filled box */
font-size: 9.5pt;
line-height: 1.45;
color: #333;
}
.with-summary > p:not(.summary) { margin: 0 0 6pt; font-size: 9pt; }
</style>What breaks when it is built the obvious way
Putting break-inside: avoid on the summary box alone. It keeps the box whole and lets it land at the foot of a page with its heading above and its section below, which is the one position where it helps nobody.
How to prove it survived pagination
Adjust the text until a section heading falls near the bottom of a page. The heading, the box and the first paragraph should all move together to the next page. Then read the box and the first paragraph one after the other and check they do not say the same thing.
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.
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.
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.
Ruled lines sized for handwriting on a printed form
An open area of ruled lines for somebody to write on, on a form completed by hand.
Multi-page report, as a complete file
The whole document with this block already in place, ready to copy and change.
break-after 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.