Skip to main content

Template authoring

Write one template that turns a JSON request into a PDF: pick an engine, validate and shape the data, style the printed page, reuse fragments, ship assets, and control when the browser prints. The pages below are ordered so each builds on the ones above — start at Template structure and read down.

The engines are logic-light on purpose: no helper does arithmetic or formats a number. There is none that adds two values, multiplies a quantity by a price, or renders one as currency. Every derived value — a line total, a subtotal, tax, a grand total — is computed by whatever builds the request, and the template places what it is handed.

One exception is worth knowing before you pick an engine, because the choice is expensive to reverse: the Go engine carries Go's own template built-ins, printf among them, so it can render 27.2 as 27.20 and 0.2 as 20% on its own. It still does not add anything up.

  • Assemble several documents into one PDF (planners, merging, remote docs) — Compositions.
  • Assert layout invariants (a block must not split across a page, a table must land where you expect) with jq or JavaScript — Layout rules.
  • Run the server on your templates, preview in the tester UI, validate, and ship an image — Template workflow.
  • Find out why a render came out wrong — Reading a render's problems.
  • The exact render endpoint, schema publishing, and error codes — Reference.
  • When the request data is untrusted, never feed it to {{{triple}}}, the markdown/embed_* helpers, or into src/href/URL positions — Security model.