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:

  1. Bundled fonts (see CJK & fonts).
  2. 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: 0 is rejected. Use style.color: transparent if you want invisible text.
  • align: justify ignores the last line. That's intentional and matches what readers expect.
  • padding doesn't collapse with siblings' margins. Lines and rows compose; nothing magically merges. If you put two spacer: "8mm" next to each other, you get 16 mm.
  • A col with body: [] is legal. It takes up its span and adds nothing visually. Useful for indentation: [{ span: 2 }, { span: 10, body: [...] }].

Something unclear or missing on this page?