CSS for paged documents, and what actually works

@page declares the properties of the page box itself: its dimensions and its margins, which are things no element selector can reach.

The size descriptor inside @page sets the paper dimensions, either by name (A4, Letter) or as an explicit width and height.

The margin descriptor inside @page sets the unprintable border around the content area of every page.

Page pseudo-classes let the first page, and left and right pages in a double-sided document, carry different margins from the rest.

A named @page rule plus the page property on an element lets one part of a document use a different page box from the rest.

The page margin boxes are sixteen named regions around the page box, such as @top-center and @bottom-right, each of which can hold generated content that repeats on every page.

counter(page) and counter(pages) are automatic counters holding the current page number and the total, intended to be used in generated content.

break-inside: avoid asks the layout not to put a page break inside this element.

break-before: page starts a new page before this element, whatever is left of the current one.

break-after: avoid asks the layout not to break immediately after this element, which in practice keeps a heading attached to its section.

page-break-before, page-break-after and page-break-inside are the original properties from CSS 2.1. The break-* properties replaced them and cover fragmentation in columns and regions as well as pages.

orphans sets the minimum number of lines of a paragraph that can be left at the bottom of a page; widows sets the minimum that can be carried to the top of the next one.

box-decoration-break decides whether an element that fragments across a break gets its border and padding applied once across the whole thing (slice) or on each fragment (clone).

Rows inside a thead element repeat at the top of every page the table runs onto. This is markup, not CSS: there is no property that creates the behaviour.

Multi-column layout flows content into columns, and in a paged context those columns fill one page before the flow continues on the next.

print-color-adjust: exact tells the renderer not to optimise colours away for printing, which is the per-element counterpart to the render's printBackground option.

The print media type matches when a document is being laid out for a paged medium, which a PDF render is.

prefers-color-scheme matches the environment's colour preference, which in a headless render is a default rather than anyone's choice.

Fixed positioning places an element relative to the viewport. A paged document has either one viewport per page or none, depending on the engine, so the element repeats on every page or appears once.

image-rendering hints at the scaling algorithm, but blurry images in a PDF are almost always a resolution problem rather than an algorithm problem.

A background set on html or body covers the canvas, which in a paged context means every page, though how it repeats depends on whether it is sized to the page or to the document.

Opacity works and produces real transparency in the output. Blend modes are composited during rendering, which means the result is correct and the layering information is gone.

Shadows are backgrounds as far as print optimisation is concerned, so they are dropped along with background colours unless backgrounds are enabled.

@font-face declares a font and where to fetch it. The fetched font is embedded in the output, so the document renders identically for a reader who has never had the font installed.

font-display controls what happens while a font is loading: swap shows fallback text immediately, block waits, optional gives up quickly.

unicode-range restricts a @font-face to a set of code points, so the browser only uses that face for characters inside the range.

font-variant-numeric: tabular-nums switches to fixed-width digit glyphs, so every digit occupies the same horizontal space.

hyphens: auto lets the layout break words at syllable boundaries, using a dictionary for the language declared on the document.

overflow-wrap: break-word allows a break inside a word when the line has no other option; anywhere is more aggressive and also affects how the minimum width is calculated.

white-space: pre preserves formatting and refuses to wrap, which on a page means everything past the margin is lost. pre-wrap preserves the formatting and allows wrapping.

Justified text stretches the spaces on each line so both edges align. It is the default in most printed books and it needs hyphenation to look right.

Line height sets the distance between baselines. Print conventions differ from screen conventions, and copying the screen value produces a document that looks loose and runs long.

text-wrap: balance distributes a short block of text evenly across its lines rather than filling each line greedily, which prevents a heading ending with one word alone.

Physical units mean a real measurement in the output. A millimetre in a PDF is a millimetre on paper, which is not true of a millimetre on a screen.

CSS defines one inch as 96 pixels, so A4 at 210mm wide is 793.7 pixels. The fraction is the reason pixel-based page layouts drift.

Viewport units resolve against the render viewport, which in a paged context is one page. 100vh is the height of a page, not the height of the document.

CSS works at 96 dots per inch. Print quality is conventionally 300, so an image needs roughly three times its CSS pixel dimensions to look sharp on paper.