Skip to content

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 render pages_report.html -o pages_report.pdf
kolinsky inspect pages_report.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:

@page wide { size: A4 landscape }
.appendix { page: wide }

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 by string-set (the current chapter title in the example above), and
  • element(NAME) shows a running element moved out of the flow with position: 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>
kolinsky render pages_plain.html -o letter.pdf --page-size letter --margin "1in 0.75in"

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.