Layout reference

Every tag, attribute, value type and limit of the XML layout language for PDF templates, with a skeleton and the rules checked when you save.

The layout is a small XML document. Every template starts with <document>. This page lists every tag and attribute that exists. Anything else is refused when you save, and all problems are listed at once with their line numbers.

Skeleton

<document page="A4" margin="16mm" font-size="10">
  <class name="muted" color="#6b7280" font-size="9"/>
  <header>
    <row valign="bottom">
      <col w="8"><h2>{{.org.name}}</h2></col>
      <col w="4" align="right"><h1>INVOICE</h1></col>
    </row>
    <hr/>
  </header>
  <footer><text class="muted" align="right">Page {page} of {pages}</text></footer>
  <text>Hello</text>
</document>

Rules in short

  • One root <document>. Text must sit inside <text>, a heading (<h1>–<h3>) or a <td>.
  • At most one <header> and one <footer>.
  • Text styling (font, font-size, color, bold, italic, align, line-height) is inherited by everything inside.
  • Named styles: declare <class name="…"/> directly under <document> and use it with class="name other". An element's own attributes win; later classes beat earlier ones. Class names start with a letter and are up to 32 letters, digits, _ or -.
  • Character entities such as &nbsp; and &copy; are understood.
  • Fonts are built in (Noto Sans, Noto Serif, Noto Sans Mono) and include characters such as ₹.

Value types

Type Accepts
Length A number with pt (default), mm, cm, in or px, for example 12, 4mm, 1in. Up to 5000.
Color Hex such as #1a1a1a or #fff.
Boolean true or false.
Edges (padding, margin) One to four lengths, written like CSS: 8, 8 12, 8 12 8 12.
align left, center, right.
valign top, middle, bottom.
font sans, serif, mono.
lines none, rows, grid.
orientation portrait, landscape.
line-height A multiplier from 0.8 to 3.
page A3, A4, A5, Letter, Legal, or a custom "<width> <height>" such as "80mm 200mm" (each at least 1in).

Elements

document

The root. Attributes: page (default A4), orientation (default portrait; a landscape setting swaps the page sides), margin (default 15mm), gap, plus the text attributes. Defaults for text are sans font, 10pt, line-height 1.35, near-black. Can contain class, header, footer, pagebreak and any block element.

class

A named bundle of attributes. Takes name and any style attribute that other elements take. It has no content and must sit directly under <document>. Each name can be defined only once.

Repeat on every page. Attributes: gap, text attributes, margin-top, margin-bottom. The gap between header and body, and between body and footer, is 12pt unless you set margin-bottom on the header or margin-top on the footer. {page} and {pages} are filled in here.

text, h1, h2, h3

Paragraphs and headings. Attributes: text attributes, margin-top, margin-bottom; <text> also takes background. Headings default to 20pt (h1), 15pt (h2) and 12pt (h3), bold, and are never left alone at the bottom of a page. Inside you can use <b>, <i>, <span> and <br/>.

span, b, i, br

Inline styling. span takes font, font-size, color, bold, italic. b is bold, i is italic, br is a line break.

row and col

A 12-column grid.

  • row attributes: gap (default 12), valign, class, margin-top, margin-bottom. It holds only <col> elements and at least one.
  • col attributes: w (whole number 1 to 12), gap, text attributes, box attributes.
  • Give every col a w and the widths must add up to 12, or give none and the columns split equally.
  • A row is never split across pages.

box

A container with a look. Attributes: padding, background, border, border-color, radius, gap, text attributes, margin-top, margin-bottom. A border has a default light grey colour. A box that runs onto a second page is drawn again on that page.

table, column, tr, td

  • table attributes: lines (rows by default, or none or grid), line-color, stripe (a colour for alternate rows), cell-padding (default 4), text attributes, margins. It holds <column> and <tr> elements.
  • column attributes: w (a positive number, relative width) and align. Declare columns to set widths and alignment.
  • tr attributes: header (true for header rows), background, text attributes. Header rows must come first and repeat at the top of every page.
  • td attributes: span (a whole number, merges cells), background, text attributes.
  • A row cannot span more cells than the table declares columns.

image

Attributes: src (required), width, height, align, class, margins. src must be a base64 data:image/…;base64, address (PNG, JPEG or GIF). Size defaults to the image's own size, scaled down to fit the page width. Give one of width or height to keep the proportions.

watermark and protect

<watermark text="DRAFT" opacity="0.15"/> stamps the text diagonally across every page. text is up to 40 characters and an empty text prints nothing; opacity runs from 0.05 to 1 and defaults to 0.15.

<protect password="…"/> makes the generated file open only with that password, up to 127 characters. The password must come from a record field, for example {{.record.values.pan}}; a typed-in password is refused when you save.

See Passwords, watermarks and combined PDFs.

hr

A horizontal line. Attributes: thickness (default 0.75), color, class, margins.

spacer

Blank vertical space. Attribute: h (default 12).

pagebreak

Starts a new page. No attributes.

Attribute tables

Group Attributes
Text font, font-size, color, bold, italic, align, line-height, class
Box padding, background, border, border-color, radius
Spacing margin-top, margin-bottom

Limits

  • Template source: up to 256 KB.
  • Filled-in document: up to 8 MB of layout and up to 500 pages.
  • Margins, header and footer must leave at least 1 inch for the body.
  • Error lists are cut off after 50 problems.

Common errors

Message Fix
not well-formed XML: … A tag is not closed or an & is not escaped in fixed text.
the root element must be <document> Wrap everything in <document>.
unknown element / unknown attribute "x" Check the spelling against the lists above.
not allowed inside <x> Move the element. For example <col> belongs inside <row>.
col widths sum to N, must be 12 Adjust the w values.
give every <col> a w, or none (equal split) Set w on all columns or none.
header rows come first Move header="true" rows above body rows.
row spans N cells but the table declares M columns Remove cells or declare more <column> elements.
image src must be a base64 data: URI Embed the image as a data: address.
unknown class "x" Declare <class name="x"/> under <document>.