A few tips with Paged.js

This page collects a few practical tips for using Paged.js when you need precise HTML-to-PDF layouts with Doppio.

You can find additional details in the Paged.js documentation.

The @media page query

To configure your PDF with Paged.js, start by adding an @page rule inside a style tag in your HTML document.

css

@page {
    size: A4;
    margin: 20mm;
}

The size property defines the page size. A4 is common, but you can also use other standard sizes such as A3 or A5, or provide explicit width and height values.

The margin property sets the margin for each page of the document (20mm in this example). This is often expressed in mm or cm, since PDFs are frequently designed for print-like formats.

INFO

For Doppio parameters, you can also set the format using:

{ "page": { "pdf":{ "format":"A4" } } }

This ensures the render format is explicitly set to A4.

The sixteen margin boxes of a page

Page margins are divided into 16 distinct areas that can be used for automatically generated elements such as page numbers or headers. These areas are called margin boxes.

Each box can be customized with its own margin, border, padding, and content. The default dimensions of these boxes are dictated by the page box's overall margin.

This layout is the one defined by the W3C specification.

To insert content into these margin boxes, add nested CSS rules.

css

@page {
    size: A4;
    margin: 20mm;

    /* Top-center Margin with PagedJS */
    @top-center {
        vertical-align: center;
        text-align: center;
        background: #fafafa;
        color: purple;
        content: "Top-center margin";
    }
}

This adds the text Top-center margin to the @top-center margin box. The vertical-align and text-align properties center the text.

Display page numbers

A common PDF requirement is to display page numbers. To do that, add counter(page) to the content property of the margin box where you want the number to appear.

css

@page {
    size: A4;
    margin: 20mm;

    /* Counter page in bottom-right corner with PagedJS */
    @bottom-right-corner {
        vertical-align: center;
        text-align: center;
        background: #fafafa;
        color: purple;
        content: "P. " counter(page);
    }
}

Here, the page number appears in the bottom-right corner in purple, formatted as P. 10.

Start on a new page

Paged.js automatically creates a new page when there is too much content for a single page. Sometimes, though, you need to decide exactly where a new page should start, for example when each chapter should begin on a new page.

For this, you can use the property break-before: page on the CSS class you want to start on a new page.

css