Migrating Templates From v2 to v3

The v2 and v3 PDF renderers use the same Liquid template files – so your Liquid files do not need to be rewritten. What changed is the rendering engine: v2 uses headless Chromium, v3 uses OpenHTMLtoPDF (a CSS 2.1 engine). As a result, some CSS and fonts render differently or are not supported under v3.

Note

Always preview a template after switching it to v3, and compare the output against the v2 result before promoting it to production use.

Info

To avoid affecting live invoices while you migrate, clone the template first, switch the clone to v3, and validate it before assigning it. For the basic v3 setup, see Configuring v3 Templates.

Discontinued CSS

The v3 engine supports CSS 2.1 plus print extensions – not modern browser CSS. Replace the following before switching:

Not supported in v3	Use instead
Flexbox (`display: flex`)	Table-based layout or floats
CSS Grid (`display: grid`)	Table-based layout
`calc()`	Pre-computed fixed values
CSS custom properties (`var()`)	Literal values, or Liquid variables
Transitions and animations	Remove (not applicable to print)
`@media` queries other than `@media print`	A single print stylesheet
JavaScript	Not supported (also not supported in v2)

v3 does support several print-oriented features that are worth using: @page rules (size, orientation, margins), page-break-*, page numbering via counter(page)/counter(pages), repeating table headers (<thead>), footnotes (float: footnote), inline SVG, CSS transforms, border-radius, box-sizing, and right-to-left/bidirectional text.

Fonts

The default font has changed. The engine default font changed from Chromium's built-in fonts to the built-in Noto families (Noto Sans, Noto Serif, Noto Sans Mono, with symbol/emoji/math fallback). Text that relied on the engine default will look different under v3 – set font-family explicitly wherever the exact look matters.

In addition, the embedding format has changed. v2 accepts web fonts (WOFF/WOFF2); v3 accepts TTF only (static TrueType – variable fonts are not supported). A web font that was embedded for v2 must be re-supplied as a TTF data: URI. Embedding remains optional in both. For details, see Embedding Assets.

Headers, Footers and Page Counters

The template Page Header and Footer record fields are not consumed by the v3 engine. In v3, page headers, footers and page counters are defined in the Liquid file using print CSS – @page margin boxes with the counter(page) and counter(pages) functions.

For example:

@page {
    size: A4;
    margin: 2cm 1.5cm 3cm 2.5cm;

    @bottom-center {
        content: "Page " counter(page) " of " counter(pages);
    }
}

For details, see Defining Headers, Footers and the Page Counter.

Document Metadata

Set the PDF document metadata from the Liquid file: the title via the <title> element (or <meta name="title">), and author, subject and keywords via the corresponding <meta> tags.

Formatting Options

v3 adds formatting options that are set as JSON in the template's PDF Options field (currency, currencyDisplay including narrowSymbol, escape, strict) and applied in the Liquid file through the decimal, currency, percent and money filters. For details, see PDF Options.

Info

While validating a migrated template, set "strict": true in the PDF Options field. Strict mode turns rendering-engine warnings into hard errors, which surfaces unsupported CSS instead of silently ignoring it. Remove it once the template renders cleanly.

Migration Checklist

Clone the template and switch the clone's PDF Renderer field to v3, then preview.
Replace Flexbox and Grid with table-based layout or floats.
Remove calc() and CSS custom properties (var()).
Re-embed web fonts as TTF data: URIs, or rely on the Noto defaults.
Embed images as data: URIs (external resources are not loaded).
Move headers, footers and page numbers to @page rules and page counters.
Set document metadata via <title> and <meta> tags.
Optionally set "strict": true in PDF Options to catch unsupported CSS, then preview again.
Promote the migrated template.