Templates Guide

DocGenLab supports two types of templates: DOCX (Microsoft Word) and HTML. Both use Jinja2 syntax for dynamic content.

Choosing a Template Type

	DOCX (Word)	HTML (Builder)
Best for	Legal docs, letters, high-fidelity layouts	Invoices, forms, web-native content
Styling	Full Word formatting preserved	CSS / inline styles
Tables with loops	Native Word rows	Standard HTML <table>
Images	Alt-text token binding	{{ img_key }} anywhere

---

1. DOCX Templates

Upload a .docx file created in Microsoft Word. DocGenLab automatically extracts all {{ token }} placeholders and builds the token list for you.

Basic Variables

Dear {{ client_name }},

Your invoice #{{ invoice_number }} for {{ amount }} is due on {{ due_date }}.

Conditional Logic

{% if is_paid %}
  ✓ PAID IN FULL
{% else %}
  Please remit payment by {{ due_date }}.
{% endif %}

Loops in Tables

Place the {% for %} tag inside the first cell of the row you want to repeat, and {% endfor %} in the last cell of the same row. docxtpl will repeat the entire row for each item.

Item	Qty	Unit Price	Total
{% for item in line_items %} {{ item.name }}	{{ item.qty }}	{{ item.unit_price }}	{{ item.total }} {% endfor %}

The matching input_json for the above:

{
  "line_items": [
    { "name": "Widget A", "qty": 2, "unit_price": 50, "total": 100 },
    { "name": "Widget B", "qty": 1, "unit_price": 200, "total": 200 }
  ]
}

Images in DOCX

1. Insert a placeholder image in your Word document.
2. Open the image's Alt Text panel (right-click → Edit Alt Text).
3. Set the alt text to the token name: {{ img_signature }}.
4. Pass the token value as a public URL or Base64 data URI in your data.

Image token naming

Any token starting with img_ is automatically treated as an image token (e.g., img_logo, img_signature).

---

2. HTML Templates (Builder)

Create templates directly in the Template Builder. The editor supports rich formatting, tables, and all Jinja2 syntax.

Basic Variables

<h1>Invoice #{{ invoice_number }}</h1>
<p>Bill to: <strong>{{ client_name }}</strong></p>

Conditional Logic

{% if status == 'paid' %}
  <span class="badge-green">PAID</span>
{% else %}
  <span class="badge-red">OUTSTANDING — Due {{ due_date }}</span>
{% endif %}

Loops in Tables

<table>
  <tr><th>Item</th><th>Price</th></tr>
  {% for item in line_items %}
  <tr>
    <td>{{ item.name }}</td>
    <td>${{ item.price }}</td>
  </tr>
  {% endfor %}
</table>

The matching input_json:

{
  "line_items": [
    { "name": "Consulting", "price": 500 },
    { "name": "Support",    "price": 200 }
  ]
}

Images in HTML

<img src="{{ img_logo }}" alt="Company Logo" />

Pass the value as a public URL or base64 data URI:

{
  "img_logo": "https://example.com/logo.png"
}

---

Token Types

When you open a template, the Variables panel on the right shows each detected token and its type. Types control how the Generate form renders the input field.

Type	Use	Example value
Text	Plain strings, numbers, dates	"John Doe", "2024-01-15"
List	Arrays for {% for %} loops	[{"name": "A"}, {"name": "B"}]
Image	URLs or base64 images	"https://..." or "data:image/png;base64,..."
Date	Date values	"2024-01-15"

DocGenLab auto-detects list type when it finds a {% for x in TOKEN %} loop referencing that token. You can override the type manually in the Variables panel.

---

Rich Media Helpers

These built-in helpers work in both DOCX and HTML templates and are called like normal Jinja2 expressions.

QR Codes

{{ insert_qr(url, size=150) }}
{{ insert_qr('https://example.com/verify/' ~ invoice_id, size=100) }}

Parameter	Default	Description
url	required	URL to encode
size	100	Size in pixels
margin	4	Quiet zone margin
color	"black"	Foreground colour
bg_color	"white"	Background colour

Barcodes

{{ insert_barcode(value, format='code128') }}
{{ insert_barcode(order_id, format='code128', bar_width=0.3, height=20) }}

Parameter	Default	Description
value	required	Value to encode
format	'code128'	Barcode format
bar_width	0.2	Bar width (mm)
height	15	Height (mm)
display_text	True	Show human-readable text

Google Maps

{{ insert_map(location, zoom=13) }}
{{ insert_map('Mumbai, India', width=600, height=300, zoom=12) }}

---

Template Versions

Every time you save a template, DocGenLab creates a new version. You can view the full history in the Versions tab of a template and roll back to any previous version at any time.

See the Template Versioning guide for details.

---

Best Practices

1. Use snake_case: {{ client_name }} is clearer than {{ clientName }} and avoids case-sensitivity issues.
2. Test with JSON input: On the Single Generate tab, switch to JSON mode to test complex nested structures (lists, nested objects) before using Bulk Generation.
3. UAT first: Build and test templates in UAT environment, then promote to Production.
4. PDF vs DOCX output:
   • PDF — read-only, fixed layout, best for final delivery.
   • DOCX — editable, best for drafts or documents the recipient needs to modify.