Style and units
Exact rules for parsing colours, lengths, fonts, and how the engine resolves "what does style.font mean here".
Style and units
The pedantic version of how the engine reads style values. Read Templates first if you just want the everyday cases.
Lengths
Anywhere a length appears (margins, spacers, image dimensions, table heights), the value can be:
<number> → points
<number><unit> → unit-converted
[ <number>, ... ] → array of points (used for [width, height])
Supported units:
| Unit | Conversion |
|---|---|
pt |
1 pt = 1/72 in (the base unit). |
mm |
1 mm ≈ 2.834645669 pt. |
cm |
1 cm = 28.346456693 pt. |
in |
1 in = 72 pt exactly. |
Whitespace between number and unit is not allowed. "20 mm" is a parse error; "20mm" is fine.
Numbers can have decimals: "0.5in", "2.54cm". Negative values are rejected for sizes (margins, spacers, dimensions) but accepted for offsets in page.background.x / page.background.y.
Colours
Hex strings only:
| Form | Example | Notes |
|---|---|---|
#rgb |
#fff |
Each digit is doubled (#fff → #ffffff). |
#rrggbb |
#0090a8 |
Standard 24-bit RGB. |
#rrggbbaa |
#0090a8aa |
RGB + alpha. Alpha is 0x00 (fully transparent) to 0xff (opaque). |
transparent |
transparent |
Shorthand for #00000000. |
There's no support for rgb(), hsl(), named colours, or CMYK direct input. If you need a CMYK colour profile, request PDF/X output via options.pdfa (PDF/A-2x supports CMYK working spaces).
Fonts
style.font accepts a family name, not a file path. Names are matched case-insensitively against:
- Bundled fonts (see CJK & fonts).
- Custom fonts uploaded to your account.
If the family doesn't exist, the engine falls back to Inter for Latin codepoints and the appropriate Noto Sans CJK for CJK codepoints. There's no error — the request still succeeds. The dashboard's Logs view shows a warning when a fallback was used.
style.weight and style.style are independent:
weight |
style |
What you get |
|---|---|---|
regular |
regular |
Regular Roman. |
bold |
regular |
Bold Roman. |
regular |
italic |
Regular Italic. |
bold |
italic |
Bold Italic. |
If your custom font doesn't have, say, a bold italic variant, the engine refuses to synthesise one — the request renders the closest available variant and emits a warning log.
Alignment
style.align for text:
| Value | Effect |
|---|---|
left |
Default. |
center |
Centred within the parent. |
right |
Right-aligned. |
justify |
Last line left-aligned, others justified. Latin/CJK only. |
align on a col:
| Value | Effect |
|---|---|
left |
Children align to the left edge of the column. |
center |
Children centred horizontally. |
right |
Children align to the right edge. |
A col with align: right containing a text with align: left resolves to the text's value (innermost wins).
Padding and spacing
padding accepts the same shapes as margin:
"padding": "4mm"
"padding": { "top": "4mm", "right": "8mm", "bottom": "4mm", "left": "8mm" }
"padding": [4, 8] // [vertical, horizontal] in pt
"padding": [4, 8, 4, 8] // [top, right, bottom, left] in pt
gap (between cols, between table rows) is a single length only.
Numbers and dates
The engine doesn't auto-format numeric data. {{.total}} prints whatever number you sent. Use printf:
{{.amount | printf "%.2f"}} → 1234.50
{{.amount | printf "%,.2f"}} → 1,234.50 (Go fmt's comma flag)
{{.amount | printf "$%.2f"}} → $1234.50
For dates, use formatTime:
{{formatTime "2006-01-02" .createdAt}} → 2026-04-14
{{formatTime "Jan 2, 2006" .createdAt}} → Apr 14, 2026
{{formatTime "2 January 2006 — 15:04" .createdAt}} → 14 April 2026 — 18:42
The format string is a Go reference time, not strftime. 2006-01-02 is the canonical form.
Reserved variables
Inside {{ ... }} you can read:
| Name | Type | Notes |
|---|---|---|
.<your-data-fields> |
depends | From the request data block. |
.page |
int | 1-indexed current page (header/footer/body). |
.pages |
int | Total page count. |
.now |
time.Time | The render's started_at. Useful for "Generated on …" footers. |
.now is set per request, not per page, so it's stable across pages within the same render.
Things that surprise people
fontSize: 0is rejected. Usestyle.color: transparentif you want invisible text.align: justifyignores the last line. That's intentional and matches what readers expect.paddingdoesn't collapse with siblings' margins. Lines and rows compose; nothing magically merges. If you put twospacer: "8mm"next to each other, you get 16 mm.- A
colwithbody: []is legal. It takes up itsspanand adds nothing visually. Useful for indentation:[{ span: 2 }, { span: 10, body: [...] }].
Related
Something unclear or missing on this page?