Multi-page & page breaks
Headers, footers, explicit breaks, repeating table headers, page numbers — everything that has to "just work" on page 47.
Multi-page & page breaks
Most templates fit on one page. The interesting cases are the ones that don't.
Auto-pagination
You don't have to do anything to get page breaks. When the body overflows the page, the engine inserts a break and continues. Tables split row-by-row; text paragraphs split line-by-line; rows and columns are kept together if there's room, and broken across a page if not.
{
"template": {
"page": { "size": "A4", "margin": "20mm" },
"body": [
{ "text": "Long article…" }
]
},
"data": { "article": "<5000 words>" }
}
The above renders correctly on however many pages it needs.
Explicit page break
Sometimes you want the break to land at a specific point — start a new chapter, end a contract page, separate cover from contents:
{ "page-break": true }
A more controlled variant:
{ "page-break": { "before": "section_2", "if": "{{gt .pageCount 0}}" }}
| Field | Type | Notes |
|---|---|---|
before |
string | Anchor name, useful for cross-references. |
if |
string | A Go-template expression that evaluates to truthy. |
Headers and footers
Set on template, repeated on every page:
{
"template": {
"page": { "size": "A4", "margin": { "top": "30mm", "bottom": "20mm" }},
"header": [
{ "row": [
{ "col": { "span": 6, "body": [{ "text": "Acme, Inc.", "style": { "weight": "bold" }}] }},
{ "col": { "span": 6, "align": "right", "body": [{ "text": "{{.title}}" }] }}
]}
],
"footer": [
{ "text": "Page {{.page}} of {{.pages}}",
"style": { "align": "center", "color": "#999" }}
],
"body": [...]
}
}
The header/footer have access to two extra template variables:
| Variable | Type | Notes |
|---|---|---|
.page |
integer | 1-indexed current page. |
.pages |
integer | Total page count. |
Yes, the engine renders the body twice in some pathological cases to know the total page count. In practice, layout is fast enough that it doesn't matter.
Different first page
Common pattern: a cover page without the header/footer, then header/footer for the rest. Set firstPage overrides:
{
"page": {
"size": "A4",
"firstPage": {
"header": [],
"footer": []
}
},
"header": [...],
"footer": [...],
"body": [...]
}
firstPage accepts the same keys as page (margin, header, footer, background, orientation).
Table page breaks
Tables paginate row-by-row. The header row is repeated on each page.
{
"table": {
"columns": [{ "span": 8 }, { "span": 4, "align": "right" }],
"header": [[{ "text": "Item" }, { "text": "Amount" }]],
"rows": [...],
"style": { "headerRepeat": true }
}
}
headerRepeat: true is the default. Set to false if you want the header only on the first page (rarely useful — keep the default).
A footer row (table.footer) appears once at the end of the last page. If you need a per-page footer, use the page-level footer instead.
Avoiding orphan rows
By default, single-row orphan / widow rules apply: if a header row would be the last thing on a page, it migrates with the next data row to avoid stranding it.
To force a group of rows to stay together (e.g. an "item + sub-items" cluster):
{ "rows": [
[{ "text": "Item A" }, { "text": "$100" }],
{ "keep-together": true,
"rows": [
[{ "text": " Sub-item 1" }, { "text": "$60" }],
[{ "text": " Sub-item 2" }, { "text": "$40" }]
] },
[{ "text": "Item B" }, { "text": "$200" }]
]}
Page-level backgrounds
For letterheads, watermarks, "DRAFT" stamps:
{
"page": {
"size": "A4",
"background": [
{
"text": "DRAFT",
"style": { "fontSize": 96, "color": "#cccccc88", "align": "center" },
"x": 0, "y": "100mm",
"rotation": -30
}
]
},
"body": [...]
}
background items use absolute positioning (x, y) and are drawn before the body — they sit behind it. rotation rotates around the node's centre, in degrees, counter-clockwise.
Anything in background repeats on every page. For first-page-only, use page.firstPage.background.
Mixed page sizes
Sections inside one document can use different page sizes by emitting a page-break with overrides:
{
"page-break": {
"page": { "size": "Letter", "orientation": "landscape" }
}
}
Subsequent body content uses the new page settings until the next override.
Page numbers in tables
Want a row's footer to show "page X" of where it ends up?
{
"table": {
"columns": [{ "span": 6 }, { "span": 6, "align": "right" }],
"rows": [...],
"footer": [
[{ "text": "Continued on page {{add .page 1}}" }, { "text": "" }]
]
}
}
add is one of the helpers available inside template expressions — see the helpers reference.
Performance with thousands of pages
The engine streams output; it does not buffer the whole PDF before sending. Memory is roughly one page's worth, regardless of total page count. We've seen real customer documents over 5,000 pages render in well under 30 s.
If you're hitting the 30 s timeout, the cause is almost always:
- A table with no
keep-togetherrules and millions of rows. Try splitting into multiplerowsarrays in chunks. - A Go-template loop that's accidentally O(n²). Profile with smaller
datafirst. - An external image fetch that's the slow step (see Images).
Related
- Templates → — the basic building blocks.
- Document schema → — full grammar.
- Performance → — benchmarks, caching, gzip.
Something unclear or missing on this page?