Templating guide

​

Overview

Every document Zenskar generates on your behalf, invoices, credit notes, payment receipts, refund receipts, and contracts, starts as an HTML template written in Mustache, a logic-less templating language. You write the layout once in Communications > Document Templates; Zenskar fills in the placeholders with real data each time a document is generated and converts the result to PDF. This page covers the parts of Mustache and template authoring that apply to every document type. For the variables specific to one document type, see its reference page:

---

​

How Mustache works

Zenskar renders templates with standard Mustache syntax:

• Variables: {{variable_name}} is replaced with a value, for example a customer’s name. Zenskar HTML-escapes variables by default; if a value legitimately contains markup (an address with embedded <br/> line breaks, for instance), use the unescaped, triple-brace form instead: {{{variable_name}}}.
• Sections: {{#document_lines}} ... {{/document_lines}} repeats the enclosed block once per item in a list, used for line items, tiers, and similar repeating data.
• Inverted sections: {{^field}} ... {{/field}} renders the enclosed block only when field is empty, false, or absent. This is the standard way to provide fallback content for an optional field, for example:
  {{#customer.tax_id}}
    Tax ID: {{customer.tax_id}}
  {{/customer.tax_id}}
  
  renders the tax ID line only when the customer has one on file, and simply omits it otherwise.

​

Syntax quick reference

---

​

Data type conventions

Every document-type reference page below expresses each variable’s type using the same conventions:

---

​

Common variables

The following variables are available across billing document templates (Invoice, Credit Note, Payment Receipt, Refund Receipt, Contract):

---

​

Writing template HTML that renders well as a PDF

Zenskar converts your template HTML to PDF after Mustache substitution runs. Because HTML-to-PDF rendering can differ from how a browser renders the same markup, follow these practices:

• Set explicit heights. Set height: 100%; on html and body so background colors and full-bleed elements extend to the edge of the page instead of collapsing to the height of the content.
• Force color printing. Browsers and PDF engines often skip background colors and images by default when printing. Add:
  body {
    -webkit-print-color-adjust: exact;
    print-color-adjust: exact;
  }
  
• Control page breaks. Apply page-break-inside: avoid; to table rows or containers that must not be split across a page boundary, such as a line-item row or a totals block.
• Use semantic table markup. Structure tables with <thead>, <tbody>, and <tfoot> rather than plain <div> grids, so headers can repeat correctly if a document spans multiple pages.
• Choose broadly-supported fonts. Pick a font family with good international character and currency-symbol coverage, and self-host or inline it. Avoid linking external CSS files, since they may not be available at render time.
• Preview before you rely on it. Open Communications > Document Templates, select your template, and click Preview to render it against sample data. Preview renders the HTML directly and is a fast way to check layout, but it is not the same rendering path as the final PDF. Before rolling a template out, generate a real document (for example a test invoice) and confirm the PDF output matches what you expect.

---

​

Starting a new template without an existing one to copy

A brand-new document template’s code editor opens completely empty. Zenskar does not provide starter or boilerplate HTML, a duplicate action, or a reset-to-default option. If a template of the same type already exists in the same organization, opening it and clicking Edit HTML shows working markup that already uses Zenskar’s placeholders correctly, and that markup can be used as a starting point for a new template of the same type. Avoid these two shortcuts, since both can carry the wrong branding or data into a new template:

• Copying a template’s Preview output. Preview shows placeholders already resolved against sample data, so its HTML contains literal, resolved values rather than live {{placeholders}}.
• Copying HTML from a different Zenskar organization or environment, such as a sandbox or test account. That organization’s branding, sample data, or hardcoded values can end up baked into the new template instead of being filled in per customer.

If neither option applies, build the HTML from scratch using the document-type-specific variable reference pages linked above, then confirm the result with Preview and a real test document before relying on it. See Document templates for the full editing workflow.