PDF and Email Layouts

A Layout that looks right in the designer can still break in the final PDF or in an email client. Both targets are rendered by engines that support only part of modern HTML and CSS. This page collects the rules that keep documents predictable.

How the output is produced

When you save a Layout, the designer exports its HTML and CSS differently for each document type:

Document type	Export
PDF	The CSS stays in a <style> block. The export adds an @page rule with the paper size and the margins from Layout for PDF, print rules for the header, footer, page counters and tables, and page-break handling.
EMAIL	The CSS is inlined into the style attribute of every element, because many email clients drop <style> blocks.

At generation time, the server fills the Handlebars placeholders with data and, for PDF, converts the HTML to a PDF. The editor canvas and the live preview are plain browser rendering, so they do not show page breaks, running headers or the fonts of the PDF engine.

Check the real output

Use Preview pdf for PDF Layouts and Send a test email for email Layouts before you publish a change. The live preview is good for content, not for print layout.

PDF layouts

Page structure

Start every PDF Layout with Layout for PDF and keep its three areas:

• Header – logo, document title, anything repeated at the top of pages,
• Main – the document body,
• Footer – company details and the Paginator for PDF.

Do not place content directly in the wrapper outside these areas. Set the paper size in Formatter document size and the margins on Layout for PDF. Do not set paper size, page margins or a fixed width on the wrapper with your own CSS: the Layout should adapt to the selected paper size.

Running header and footer

The header and footer are meant to repeat on every page. Two HTML-to-PDF engines exist in the DMS service and the environment configuration decides which one is used:

tsm.html-to-pdf.use-legacy	Engine	Repeating header and footer
false	openhtmltopdf	Supported.
true	iText pdfHTML	Not supported. The header and footer are printed once, in the normal flow at the top of the document.

If headers and footers appear only once, check this setting of the environment before changing the Layout. The problem cannot be fixed in the HTML or CSS of the Layout. The engine that produced a PDF is shown as Producer in the document properties of the PDF, for example openhtmltopdf.com.

Build with tables

• Use the Section blocks and the Table component for columns and grids. PDF engines render tables reliably; floating and flex layouts are often ignored.
• A table header (<thead>) repeats on every page the table spans. With the openhtmltopdf engine this also works for a table nested inside a cell of another table; with the iText engine a nested table may lose its header on the following pages. Keeping long, growing tables at the top level of the main area works with both engines.
• Set background colours on the cells (th, td), not on thead or tr. Row and header group backgrounds are not painted by every engine.
• For space between two tables, use margin-top. padding on a table with border-collapse: collapse is often dropped.
• Put a checkbox and its label into separate cells of a one-row table when they must stay on one line. Inline blocks and flex rows break unpredictably in PDF.

Page breaks

Let the content flow and break pages naturally. The export already handles the common cases for tables built with the Table component: rows are kept whole, so a table breaks only between rows, and the header repeats at the top of each page the table spans (see Build with tables).

Start a new page with the component. Drag New page for PDF into the main area of Layout for PDF at the point where the next page should begin; it cannot be placed in the header or the footer. The export turns it into a page break, so no CSS is needed. Use it only where the document really must start a new page, for example before terms and conditions.

Keep a block together with CSS. No component covers this. Add page-break-inside: avoid for the element in a print rule, for example for a summary table or the signature block:

@media print {
  #summary-table { page-break-inside: avoid; }
}

Apply it to specific blocks only. Applied to every table, it pushes content to the next page and leaves large gaps.

Remove an unused table header or footer. An empty <thead> or <tfoot> still prints a blank row.

Sizes, fonts and characters

• Avoid fixed heights. height and min-height fight with page breaks: content gets cut or pushed to the next page. Control spacing with padding, margins and line height.
• Use font-weight: 600 for bold text. bold (700) looks too heavy in the PDF engine. semi-bold is not a valid CSS value and is ignored.
• Set the font explicitly. Text without a font-family is printed in the default serif font of the PDF engine, even when the designer shows it in a sans-serif font.
• Prefer standard fonts such as Arial, Helvetica or Verdana. A font that is not available to the PDF engine is replaced by a default one.
• Check special characters. Symbols such as ☑, ☐ or ✓ can print as # when the PDF font does not contain them, even though the designer shows them correctly. Use [X] and [ ] or small images instead.

Images

• Embed logos and icons as base64 images, so the PDF does not depend on external URLs.
• Keep embedded images small, around 130–200 px wide for a logo. Large embedded images have been known to render as an empty area in the PDF. The engine scales the image to its displayed width anyway.
• Use the Signature component for signatures that come from data.

Condition markers

The Condition block keeps its start, else and end markers in the HTML. They are visible in the designer, which helps editing, but as block elements they can split an inline line in the PDF. Hide them in print output only, so they stay visible in the designer:

@media print {
  .start-condition,
  .if-else-condition,
  .end-condition { display: none; }
}

Inside a numbered list (<ol>), write the condition inline instead, because a wrapper around an <li> breaks the numbering:

<ol>
  <li>Always present</li>
  {{#if showOptional}}<li>Optional item</li>{{/if}}
  <li>Always present</li>
</ol>

Email layouts

• Everything becomes inline styles. Style each element directly; selectors that depend on structure (.box p, :hover, media queries) do not survive the export.
• Use tables for columns and set widths in pixels.
• Test in real clients. Use Send a test email and open the message in the clients your recipients use, for example Outlook and Gmail.
• Keep content in Templates. Most notification emails share one Layout; the texts belong in Templates.

Data and helpers

• Escape rules. {{value}} escapes HTML. Values that contain HTML, such as rich-text fields, need {{{value}}}.
• Unknown helpers stop the document. If a Layout calls a helper that is not registered on the server, rendering fails for the whole document instead of leaving the value empty. Use the helpers from the Handlebars Reference and verify new ones with a preview.
• Separators next to optional values. Text such as {{contractNumber}} - {{amendmentNumber}} leaves a dangling - when the second value is empty. Put the separator inside the condition: {{contractNumber}}{{#if amendmentNumber}} - {{amendmentNumber}}{{/if}}.
• Loop over the right list. When a loop needs filtering, prefer a data path that already contains only the wanted items over conditions inside the loop.

Documents converted from Word

Layouts are often created by converting a Word document to HTML and importing it with Import. Check the result for these conversion leftovers:

Leftover	Fix
Merge fields such as <<[Customer.Email]>>	Replace them with Handlebars placeholders such as {{customer.email}}. They are not processed and print literally.
font-weight: semi-bold	Replace with font-weight: 600.
Heavy cell padding such as 5px on all sides	Reduce the vertical padding, for example to 2px 5px.
Brownish or dark grey text and borders from colour conversion	Compare with the original and use the intended colours.

Checklist before publishing

• The PDF starts with Layout for PDF and uses its header, main and footer areas.
• Preview pdf or Send a test email was checked with realistic test data, including long texts and empty optional values.
• Long tables are at the top level of the main area and repeat their header on page 2.
• No fixed heights, no forced page breaks without a reason, no empty table headers or footers.
• Every helper used in the Layout is listed in the Handlebars Reference or was verified on the environment.