Pages and page setup¶
The document's CSS decides the pages: @page rules set the size and the margins, margin boxes hold headers
and footers, and the break properties decide where a new page starts. This example uses all of them:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Quarterly report</title>
<style>
@page {
size: A4;
margin: 25mm 20mm;
@top-left { content: string(chapter); font: 8pt sans-serif; color: #555 }
@bottom-center { content: "Page " counter(page) " of " counter(pages); font: 8pt sans-serif }
}
/* no header or footer on the title page */
@page :first {
margin-top: 60mm;
@top-left { content: none }
@bottom-center { content: none }
}
@page :left { margin-left: 25mm; margin-right: 15mm }
@page :right { margin-left: 15mm; margin-right: 25mm }
/* a named page type for wide tables */
@page wide { size: A4 landscape }
body { font: 10pt/1.5 serif }
h1 { break-before: page; string-set: chapter content() }
h1.title { break-before: auto; font-size: 28pt }
.appendix { page: wide }
p { orphans: 3; widows: 3 }
table { break-inside: avoid; width: 100%; border-collapse: collapse }
td { border: 0.5pt solid #999; padding: 2mm }
</style>
</head>
<body>
<h1 class="title">Quarterly report</h1>
<p>Third quarter, 2026.</p>
<h1>Summary</h1>
<p>Revenue grew in every region. The details follow on the next pages.</p>
<h1>Regions</h1>
<p>North, south, east and west are reported separately.</p>
<section class="appendix">
<h1>Appendix: figures</h1>
<table>
<tr><td>Region</td><td>Q1</td><td>Q2</td><td>Q3</td><td>Q4</td><td>Total</td></tr>
<tr><td>North</td><td>120</td><td>135</td><td>150</td><td>160</td><td>565</td></tr>
<tr><td>South</td><td>90</td><td>95</td><td>110</td><td>115</td><td>410</td></tr>
</table>
</section>
</body>
</html>
kolinsky inspect prints the size of each page in points and the name of named pages, without writing a
PDF:
page 1: 595.276 x 841.89 pt
page 2: 595.276 x 841.89 pt
page 3: 595.276 x 841.89 pt
page 4: 841.89 x 595.276 pt wide
Page size¶
size takes two lengths (width, then height), one length (a square page), a page-size keyword, or a keyword
with portrait or landscape:
@page { size: A4 } /* 210 x 297 mm, the default */
@page { size: letter landscape } /* 11 x 8.5 in */
@page { size: 148mm 210mm } /* width, height */
The keywords are A0 to A10, B0 to B10, C0 to C10, JIS-B0 to JIS-B10, letter, legal and
ledger, compared case-insensitively. auto and portrait alone mean A4 portrait, landscape alone A4
landscape; when the options give a fallback page size (see below), they resolve against that size instead
of A4. An invalid value is ignored and the previous size stays.
Margins¶
margin and margin-top, margin-right, margin-bottom, margin-left inside @page set the page margins;
the page content is laid out in the box between them. Without a declaration the margin is 75 px (about
19.8 mm) on every side.
Page selectors¶
An @page rule can be limited to some pages. Several rules that match a page are combined by the cascade, the
more specific ones winning:
| selector | pages |
|---|---|
@page :first |
the first page of the document |
@page :left, @page :right |
left and right pages of a double-sided document; the first page is a right page in a left-to-right document |
@page :blank |
pages inserted empty by a forced break to a side (see below) |
@page :nth(2n+1) |
pages by position, counted from 1 |
@page wide |
pages of the named page type wide |
@page :nth(1 of chapter) |
the first page of each group of chapter pages |
@page wide:first |
a name and pseudo-classes together |
A rule with an unknown pseudo-class, or with :left and :right together, is dropped with a warning.
Named pages¶
The page property puts an element on pages of a named type, which @page NAME rules style:
A page break is forced before an element whose page name differs from the page it would start on, and the
new page takes its name. Content after a named element that has no name of its own continues on the same
page; give it break-before: page to start a new one. Each run of pages of one named element is a page
group, which :nth(... of NAME) counts.
From Rust and Python, Page::name() (Python Page.name) returns the name of each page of a laid-out
document, and None for pages without a name.
Headers and footers: margin boxes¶
Inside @page, sixteen margin boxes sit in the page margins: @top-left-corner, @top-left,
@top-center, @top-right, @top-right-corner, @right-top, @right-middle, @right-bottom,
@bottom-right-corner, @bottom-right, @bottom-center, @bottom-left, @bottom-left-corner,
@left-bottom, @left-middle and @left-top. A margin box is drawn only when its content is set to
something other than none or normal; it takes fonts, colours, borders, backgrounds and alignment like any
box.
@page {
@top-right { content: "Draft"; color: #c00 }
@bottom-center { content: "Page " counter(page) " of " counter(pages) }
}
@page :first {
@bottom-center { content: none } /* no footer on the title page */
}
The three boxes of one side share its length: a box without content leaves its space to its neighbours.
A margin box can show text taken from the document:
string(NAME)shows a string set bystring-set(the current chapter title in the example above), andelement(NAME)shows a running element moved out of the flow withposition: running(NAME).
Both are described with the other paged-media features.
Page numbers¶
The page counter numbers the pages from 1 and pages holds the number of pages. Both work in margin boxes,
and target-counter(attr(href), page) gives the page number of a link target anywhere in the document
(see tables of contents).
A page rule can reset or set the counter: @page :first { counter-reset: page 5 } numbers the pages 5, 6,
7, ... Blank pages are counted.
Page breaks¶
| property | values |
|---|---|
break-before, break-after |
auto, page, left, right, recto, verso, avoid, avoid-page |
break-inside |
auto, avoid, avoid-page |
orphans, widows |
the least number of lines of a paragraph left at the bottom of a page (orphans) or carried to the top of the next one (widows); 2 by default |
The older page-break-before, page-break-after and page-break-inside are read as shorthands of the same
properties.
break-before: left or right (recto and verso follow the writing direction) starts the element on a
page of that side. When the next page would be of the other side, one blank page is inserted; it gets the
margin boxes of its @page rules, and @page :blank can remove them.
Page size and margin from the options¶
The page size and margin given to the engine (--page-size and --margin on the command line,
default_page in Rust, page_size and margin in Python) are a fallback: they apply where the document's
own @page rules set no size or margin, as if the document began with
@page { size: ...; margin: ... }. A document that sets its own size keeps it.
<!DOCTYPE html>
<html lang="en">
<head><meta charset="utf-8"><title>Letter</title></head>
<body>
<p>A document without <code>@page</code> rules takes the page size and margin of the options.</p>
</body>
</html>
The same from Rust and Python, with the layout and the PDF as two steps. The report keeps the A4 size of its
own @page rules, so the option changes nothing there; the PDF holds the pages from 2 on:
use kolinsky::{Engine, Input, PdfOptions, RenderOptions};
fn main() -> Result<(), Box<dyn std::error::Error>> {
// The fallback page: used only where the document's @page rules set no size or margin.
let mut options = RenderOptions::default();
options.default_page.size = Some("letter".into());
options.default_page.margin = Some("1in 0.75in".into());
let engine = Engine::new();
let document = engine.layout(Input::Path("pages_report.html".into()), &options)?.output;
for page in document.pages() {
let size = page.size();
println!("page {}: {} x {} pt {}", page.index() + 1, size.width, size.height, page.name().unwrap_or(""));
}
let mut pdf = PdfOptions::default();
pdf.pages = Some("2-".parse()?);
std::fs::write("report-body.pdf", document.to_pdf(&pdf)?.output)?;
Ok(())
}
from pathlib import Path
import kolinsky
options = kolinsky.Options(page_size="letter", margin="1in 0.75in")
document = kolinsky.Engine().layout(Path("pages_report.html"), options=options)
for page in document.pages:
print(f"page {page.index + 1}: {page.width} x {page.height} pt {page.name or ''}")
Path("report-body.pdf").write_bytes(document.to_pdf(pages="2-").pdf)
An invalid page_size or margin value is an error before anything is loaded.