Page setup

OptionsCopy Anchor Link

Set page options in options. Every option is optional; an omitted one takes its default.

{
  "engine": "forme",
  "html": "<h1>Invoice</h1>",
  "options": { "paper_size": "Letter", "margin_top": "20mm", "margin_bottom": "20mm" }
}

• Top and bottom margins must leave printable height; left and right margins must leave printable width.
• An invalid value is refused with 400 invalid_request_body; an option not listed here with 400 unknown_option.

@page and the optionsCopy Anchor Link

Both engines treat a document's own @page rules the same way:

Fitting differs by engine:

• Chromium only shrinks a larger page; a smaller one is centered at 1:1.
• Forme scales the page up or down.

BreaksCopy Anchor Link

break-before, break-inside: avoid, orphans and widows behave the same on both engines.

h2 {
  break-before: page;
}

table,
figure {
  break-inside: avoid;
}

Running headers and footersCopy Anchor Link

Both engines print @page margin boxes; position: fixed repeats on every page with Chromium and is refused by Forme with 422 unsupported_document (see Forme). For <thead> and <tfoot>, see Choosing an engine.

Margin boxesCopy Anchor Link

Print a header and "Page X of Y" on every page with @page margin boxes:

<style>
  @page {
    size: A4;
    margin: 25mm 15mm;

    @top-center {
      content: "Invoice INV-2026-0042";
    }

    @bottom-center {
      content: "Page " counter(page) " of " counter(pages);
    }
  }
</style>
<h1>Invoice INV-2026-0042</h1>

Chromium: fixed elementsCopy Anchor Link

Repeat a header and footer on every page with position: fixed:

<style>
  .header,
  .footer {
    position: fixed;
    left: 0;
    right: 0;
  }

  .header {
    top: 0;
  }

  .footer {
    bottom: 0;
  }
</style>
<div class="header">Invoice INV-2026-0042</div>
<div class="footer">Acme GmbH</div>
<h1>Invoice INV-2026-0042</h1>