PDF Templates for Directus (Gotenberg)

This extension lets administrators create HTML templates and generate PDFs from Directus items using Gotenberg.

What This Extension Does

• Manage PDF templates inside Directus
• Bind each template to a target collection (for example invoices)
• Use English or Dhivehi templates
• Configure a global Gotenberg URL and optional headers
• Generate PDFs from item pages through Flows

Admin Setup Guide

Use this section if you are installing/configuring the extension.

Prerequisites

• Directus 10.10+
• A reachable Gotenberg 8 service
• Admin access in Directus (for first-time setup)

Install

1. Install this extension bundle in your Directus extensions path.
2. Restart Directus.
3. Open Directus as an admin.

On startup, the extension auto-bootstraps required collections:

• pdf_templates
• pdf_extension_settings (singleton)

Configure Gotenberg

1. Open PDF Templates module.
2. Open Extension setup (gear icon).
3. Set:
   • Gotenberg base URL (for example http://localhost:3000)
   • Optional HTTP headers JSON (for example Authorization headers)
4. Save.

Create a Template

1. In PDF Templates, create a new template.
2. Set:
   • name
   • target_collection (must match where you will trigger PDF generation)
   • language (en or dv)
3. Fill template content fields:
   • content
   • Optional header_html
   • Optional footer_html
4. Save.

Create the Flow (Required)

1. Go to Settings -> Flows.
2. Create a flow with trigger:
   • Type: Manual
   • Location: Item page
3. Add operation: Generate PDF (Gotenberg).
4. Set template_id to your template.
5. Keep this operation as the final step in the flow.

Add PDF Button on Item Pages (Optional)

1. In your target collection, add a field (for example a string field).
2. Set the field interface to PDF Flow Launcher.
3. Configure interface options:

{
  "template_id": "<pdf-template-uuid>",
  "buttonLabel": "Generate PDF",
  "action_mode": "open"
}

action_mode values:

• open: opens in a new tab
• download: downloads the PDF

If template_id is not set, launcher can auto-select the first matching template for the current collection.

Content Editor Guide

Use this section if templates/flows are already configured by an admin.

Generate a PDF from an Item

1. Open an existing item in the target collection.
2. Click Generate PDF from the launcher button or run the manual flow from the item page.
3. The PDF opens or downloads based on action_mode.

Gotenberg Config

The gotenberg_config field on a template is optional JSON that controls PDF page layout and rendering. Only whitelisted keys are forwarded to Gotenberg; unknown keys are ignored.

Supported keys:

| Key | Type | Description | | ------------------------- | ------ | ------------------------------------ | | paperWidth | string | Page width (e.g. "8.5" inches) | | paperHeight | string | Page height (e.g. "11" inches) | | marginTop | string | Top margin (e.g. "0.5") | | marginBottom | string | Bottom margin | | marginLeft | string | Left margin | | marginRight | string | Right margin | | landscape | string | "true" for landscape orientation | | scale | string | Page scale factor (e.g. "1.0") | | printBackground | string | "true" to include CSS backgrounds | | waitDelay | string | Wait before conversion (e.g. "1s") | | emulatedMediaType | string | "screen" or "print" | | generateDocumentOutline | string | "true" to generate a PDF outline |

Example:

{
  "paperWidth": "8.27",
  "paperHeight": "11.69",
  "marginTop": "2.2",
  "marginBottom": "1.6",
  "marginLeft": "0.8",
  "marginRight": "0.8",
  "landscape": "false",
  "printBackground": "false"
}

All values are passed as strings to the Gotenberg form API. See the Gotenberg Chromium docs for full details on each option.

Template Content Syntax

The template editor uses Handlebars syntax. Use the @, #, $ autocompleters in the editor to insert fields.

Field Values

{{ field }}
{{ relation.field }}

Default Values

Show a fallback when the field is null or empty:

{{default title "Untitled"}}
{{default phone_number "N/A"}}
{{default address "-"}}

Date Formatting

{{formatDate created_date}}                                        → "Apr 6, 2026"
{{formatDate created_date "en-US" format="DD/MM/YYYY"}}            → "06/04/2026"
{{formatDate created_date "en-US" format="YYYY-MM-DD"}}            → "2026-04-06"
{{formatDate created_date default="-"}}                            → "-" (if null)

DateTime Formatting

{{formatDateTime created_at}}                                      → "Apr 6, 2026, 02:30 PM"
{{formatDateTime created_at "en-US" format="DD/MM/YYYY HH:mm"}}   → "06/04/2026 14:30"
{{formatDateTime created_at "en-US" format="DD/MM/YYYY hh:mm A"}} → "06/04/2026 02:30 PM"

Format tokens: YYYY, YY, MM, M, DD, D, HH (24h), hh (12h), mm, ss, A/a (AM/PM).

When no format is provided, formatDate defaults to year/month/day and formatDateTime adds hour/minute. You can also pass Intl.DateTimeFormat options as hash parameters:

{{formatDate created_date "en-US" year="numeric" month="long" day="numeric"}}

Conditionals and Loops

{{#if field}}...{{/if}}
{{#each items}}...{{/each}}
{{#if field}}...{{else}}...{{/if}}

Comparison Helpers

{{#if (eq status "active")}}Active{{/if}}
{{#if (ne status "draft")}}Not a draft{{/if}}

Page Breaks

Insert page breaks from the editor toolbar (page break button) or manually:

<!-- pagebreak -->

Editor Features

• Alignment: left, center, right, justify via toolbar buttons
• Text formatting: bold, italic, underline, strikethrough
• Block types: paragraphs, headings (H1-H6)
• Lists: bullet and numbered
• Tables, links, images
• Page breaks: inserts a visible dashed line in the editor, renders as a page break in the PDF
• Code view: switch to raw HTML editing

Fonts

• English templates use Times New Roman (serif) by default
• Dhivehi templates use MV A Waheed (headings) and MV Faseyha (body)
• Custom fonts can be uploaded per-template or globally in extension settings

Troubleshooting

• pdf_templates or pdf_extension_settings missing after install:

  • Restart Directus once.
  • Open PDF Templates as an admin.
  • If your environment blocks runtime schema changes, ask your admin to apply schema manually from schema/.

• Button is disabled:

  • Open an already-saved item (not a new unsaved item).
  • Confirm desktop viewport (>768px). The launcher is hidden on small screens.
  • Confirm a matching template exists for that collection.

• Error saying template belongs to another collection:

  • Fix target_collection on the template so it matches the collection where you run it.

• Gotenberg errors:

  • Verify gotenberg_url in extension setup.
  • Verify optional headers are valid JSON.
  • Ensure Directus can reach the Gotenberg host.

Notes

• PDF generation uses authenticated endpoints and Directus permissions.
• Content-Type is managed automatically for multipart requests.
• Dangerous hop-by-hop HTTP headers are stripped server-side.