Word templates#

Word (.docx) is the most common authoring format and is fully supported: images, rich text, headers and footers, barcodes, charts, signatures, and PDF or DOCX output. Most "but it looks fine in Word" rendering issues come from the three quirks on this page — worth five minutes before debugging.

Authoring basics#

• Merge tags are plain text. Type {Name}, {Account.Name}, {Amount:currency:EUR:nl_NL} where the value should appear. Full syntax: Merge tag reference.
• Loops in tables. Put {#Relationship} in the first cell and {/Relationship} in the last cell of the row you want repeated — the whole row repeats once per record and the header row stays fixed. Add {RepeatHeader} anywhere inside the header row to mark it as a repeating header for very large tables. Loops in bulleted or numbered paragraphs repeat the paragraph.
• Page break per record. Put a page break (Insert → Page Break) inside a loop and every child record gets its own page.
• Cover pages. With Different First Page enabled, the PDF suppresses headers and footers on page 1. Section breaks become page breaks in the PDF.
• Images. Embed them in the document (they render in PDF automatically), or use {%Field__c:100%x}, {%Image:1} or {%asset:logo:200x} for record-driven and shared images. Compress pictures before saving: the upload limit is 10 MB.
• Fonts. DOCX output keeps your fonts. PDF output falls back to Helvetica for anything that is not Helvetica, Times, Courier or Arial Unicode MS — if a branded typeface matters, generate DOCX.
• Wingdings checkboxes (☐ ☑ via Insert → Symbol or content-control checkboxes) are translated to Unicode at PDF time; other Wingdings glyphs are not — use the symbol palette.

The run-splitting trap#

The most common cause of a tag that "doesn't resolve": Word silently splits a run mid-tag during spell-check or formatting, turning {Quantity} into three runs {, Quantity, }. The engine then never sees a complete tag. Fixes: type the tag in one go, paste it as plain text, or select it and Clear All Formatting. When debugging, unzip the .docx and check that each tag sits in one <w:t> run in word/document.xml.

Aligning columns across multiple tables — the "phantom width" trap#

Symptom. Two or three tables that look identical in Word render with subtly different column widths in the PDF; middle columns collapse and right-side columns push outward.

Why. A .docx describes column widths in two places that must agree: <w:tblGrid> on each table (the column grid, in twips — 1440 twips = 1 inch) and <w:tcW> on each cell (a per-cell override). Word reconciles disagreements at display time and shows you a clean layout; the PDF engine reads the XML literally, so small numeric differences become visible. The two drift apart when a column boundary was dragged with the mouse, when AutoFit to Contents was on, or when cells were copy-pasted between tables.

Fix, in priority order.

1. Click in the table → Table Layout → AutoFit → Fixed Column Width, for every table that must line up.
2. Table Properties → Table → Preferred width = exact centimetres or inches. Not Auto, not a percentage.
3. Select each column → Table Properties → Column → Preferred width = an exact value. Repeat for every column in every table.
4. Build one table first, then copy it to make the others. Edit only the cell contents, never the boundaries.

If that still fails, unzip the .docx, open word/document.xml, find each <w:tbl> and make the <w:tblGrid> and <w:tcW> values byte-for-byte identical across the tables that must align; re-zip and rename to .docx. Architectural alternative: use one big table with borderless divider rows between sections instead of several tables.

AutoFit settings — what each does to the PDF#

Inspecting a problematic .docx#

A .docx is a zip. Change the extension to .zip, unzip, and open word/document.xml. The table structure that matters:

<w:tbl>
  <w:tblPr> … </w:tblPr>
  <w:tblGrid>
    <w:gridCol w:w="1440" />   <!-- column 1: 1 inch -->
    <w:gridCol w:w="2880" />   <!-- column 2: 2 inches -->
  </w:tblGrid>
  <w:tr>
    <w:tc>
      <w:tcPr><w:tcW w:w="1440" w:type="dxa" /></w:tcPr>   <!-- must match grid column 1 -->
      …
    </w:tc>
  </w:tr>
</w:tbl>

Converter limits worth knowing#

The package's DOCX → PDF conversion does not behave like Word for every layout feature:

• Fonts are remapped (Calibri → Helvetica); don't rely on a specific font file.
• Page breaks work reliably (page-break-before on a paragraph).
• "Exact" table row heights are ignored — a tall exact row collapses to its content height.
• Cell shading only paints behind actual text lines. A shaded cell padded with empty paragraphs renders as a thin band; pad it with non-breaking spaces instead if you need a taller colour block.
• No true full-bleed. Content lives inside the page margins; a .docx cannot produce an edge-to-edge background. For full-bleed or per-page backgrounds use an HTML template or a Canvas template.
• Text boxes, shapes, SmartArt and Word charts are not converted — use tables for layout, {Chart:…} for charts, or insert an image.
• Even/odd page headers and multiple section headers are not supported in PDF; one header/footer set per document.
• Multi-column layouts are not supported in PDF; use tables.

Other gotchas#

• Track Changes. Save with Track Changes off and every suggestion accepted or rejected; tracked markup is treated as live content.
• Comments can leave artefacts the same way.
• Embedded objects (Excel sheets, drawings) convert hit-or-miss; replace with screenshots if output must be exact.
• Mixed portrait/landscape sections work in DOCX output but are fragile in PDF; the first section's page size may apply to the whole document.
• Watermarks inserted through Word's Design → Watermark work with constraints — scale 100 %, Washout off, no rotation — or use the template's Watermark tab for exact control. See Watermarks.
• Hyperlinks authored in Word stay clickable in the PDF.

Generating a .docx programmatically#

Consultants who build templates with a script (for example python-docx) should insert each merge tag as a single run so it can never split, and verify the tags before uploading:

from docx import Document
d = Document()
d.add_paragraph().add_run('{QuoteNumber}')                      # tag = one clean run
t = d.add_table(rows=2, cols=3)
t.rows[0].cells[0].text = 'Product'
t.rows[1].cells[0].paragraphs[0].add_run('{#Lines}{Product2.Name}')
t.rows[1].cells[2].paragraphs[0].add_run('{TotalPrice:currency:EUR:nl_NL}{/Lines}')
d.save('template.docx')

Upload it through the Command Hub (Document tab → Save as New Version) or through the REST API as a ContentVersion followed by a template save — ask Welisa for the scripted path.

What works in PDF versus DOCX#