Layout reference

Every tag, attribute, value type and limit of the PDF layout language.

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   and © are understood.
• Fonts are built in (Noto Sans, Noto Serif, Noto Sans Mono) and include characters such as ₹.

Value types

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.

header and footer

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.

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

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

Related

• Template data and helpers
• Create a template