Templates

The Templates module is the central content engine in Docuget. Every email body, PDF invoice, chart visualization, video script, and data export is a template — stored in a single templates table, rendered by Nunjucks, and routed to the appropriate output format by source_type.

For a high-level architecture overview, see Template System. For email-specific usage, see Email Templates.

---

Template Fields

---

Source Types

Each template's source_type determines how it is rendered and which output formats are available.

---

Template Editor

The template editor is a split-panel UI in the frontend:

• Left panel — filterable list of templates with icons by dest_type, search, and create/delete
• Right panel — tabbed editor for the selected template

Editor Tabs

Form Fields

The editor toolbar exposes:

• Description — template display name
• Source Type — dropdown: html, text, markdown, typst, json, xml, svg, latex, echart, remotion
• Dest Type — context-aware dropdown (changes based on source type)
• Dest Filename — output filename
• Replacer — templating engine (default: nunjucks)
• Active — toggle on/off

---

AI Integration

Templates have built-in AI assist. The earlier split Generate / Enhance buttons were replaced by a single unified panel.

AI Sidecar

One toggle opens the AI Sidecar — a CodeMirror request box on the right of the editor. You describe what you want in plain language; if the open record is empty the assistant creates, if it has content it edits — no separate mode. It sends the record's source_type, dest_type and current content as context (so you don't re-enter them) and streams the result back live (SSE, so long generations don't hit the edge timeout). Apply / Undo / Save-now gate the result. Uses the template_assistant prompt. Create a blank record with New.

Draft README with AI

The Readme tab has a ✨ Draft with AI button that documents the template from its own record (description, source_type, body/layers, form_fields, seed_json) via the readme_writer prompt. It streams markdown into the field (with a pre-draft Undo), writes in the operator's current app language, and preserves human-written notes (authorship/links) when refining an existing readme.

AI Prompt Templates

The AI system behind the Sidecar and Draft-README is configurable. Admins can manage prompt templates at /ai/prompt-templates (Intelligence Labs > AI > Prompt Templates).

Each AI prompt template has:

The AI Prompt Template Manager has 5 tabs: General, System Prompt, User Prompt, Input Fields, and Test (with embedded live testing).

Seeded AI Templates

Platform-global AI prompt templates (company_id NULL — available to every tenant) provided out of the box:

The legacy template_generator / template_enhancer prompts are superseded by template_assistant.

---

Nunjucks Filters

All templates use the same Nunjucks environment with these filters available.

Date & Time

Numbers & Currency

Strings & Encoding

Images & Media

Maps & Links

Short References

Composable Rendering

These filters call the render engine recursively (max depth: 5).

For binary outputs (PNG, PDF), these filters return a base64 data URI.

Data Format Conversion

---

Rendering Pipeline

When a template is rendered, the system follows this pipeline:

1. Lookup     → Fetch template by ID or (company_id, template_key)
2. Merge      → seed_json defaults + caller data (caller wins)
3. Resolve    → @shortref codes → full IDs
4. Resolve    → $fn: directives → live query results
5. Render     → Nunjucks processes {{ placeholders }}
6. Route      → source_type dispatcher (HTML passthrough, Marked, Typst, ECharts SSR, etc.)
7. Convert    → Optional format conversion (e.g. SVG → PNG, JSON → XLSX)
8. Cache      → Optional output caching (cache_ttl)
9. Deliver    → Return inline content, file download, or metadata

Steps 3-4 only apply when rendering through the universal Render Engine. Direct template rendering (POST /v1/templates/:id/render) skips to step 5.

Seed JSON Merging

The seed_json field provides default values. When rendering, these are deep-merged with caller-provided data, with caller values winning:

// seed_json (defaults)
{ "title": "Untitled", "color": "#000", "show_footer": true }

// caller data
{ "title": "Q1 Report", "items": [...] }

// merged result (passed to Nunjucks)
{ "title": "Q1 Report", "color": "#000", "show_footer": true, "items": [...] }

Special seed_json keys:

• _text_template — plain-text email fallback (rendered separately)
• width, height — ECharts chart dimensions
• widget_config — ChartWidget display settings (auto-refresh, format)
• style — XLSX styling options (headerStyle, alternateRowColor, borders)

---

API Reference

All endpoints require authentication (Bearer token).

Template CRUD

GET    /v1/templates                    List templates
GET    /v1/templates/:id                Get by ID
GET    /v1/templates/by-key/:key        Get by key (requires ?company_id=)
POST   /v1/templates                    Create template
PUT    /v1/templates/:id                Update template
DELETE /v1/templates/:id                Delete template

List filters:

Render

POST   /v1/templates/:id/render         Render with data (direct)
POST   /v1/templates/:id/preview-data   Preview tabular data (resolve $fn:)

curl examples:

# Create a Typst invoice template
curl -X POST https://api.docuget.com/v1/templates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "company_id": "550e8400-...",
    "description": "Standard Invoice",
    "template_key": "invoice_standard",
    "template_category": "invoice",
    "source_type": "typst",
    "dest_type": "pdf",
    "dest_filename": "invoice.pdf",
    "content": "#set page(paper: \"letter\")\n= Invoice {{ invoice_number }}\n\nDate: {{ date }}\nTotal: ${{ total }}",
    "seed_json": {
      "invoice_number": "",
      "date": "",
      "total": "0.00"
    }
  }'

# Render it
curl -X POST https://api.docuget.com/v1/templates/template_01hjd3.../render \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-2026-001",
    "date": "2026-03-21",
    "total": "1,500.00"
  }'

# List email templates
curl "https://api.docuget.com/v1/templates?company_id=550e8400-...&template_category=email" \
  -H "Authorization: Bearer $TOKEN"

# Lookup by key
curl "https://api.docuget.com/v1/templates/by-key/calendar_event_email?company_id=550e8400-..." \
  -H "Authorization: Bearer $TOKEN"

AI Prompt Templates

GET    /v1/ai/templates                  List AI prompt templates
GET    /v1/ai/templates/:id              Get by ID
POST   /v1/ai/templates                  Create
PUT    /v1/ai/templates/:id              Update
DELETE /v1/ai/templates/:id              Delete
POST   /v1/ai/completions               Execute a prompt (returns AI response)
GET    /v1/ai/logs                       Completion logs

---

Webhooks

Templates can optionally trigger webhooks on two events:

Webhooks are configured via the Webhook tabs in the template editor. See Webhooks for full webhook documentation.

Note: Automatic webhook execution after render is not yet wired — webhooks are currently stored as references for manual triggering.

---

Caching

Templates use a multi-layer caching strategy:

---

Examples

HTML Email Template

<div style="font-family: sans-serif; max-width: 600px;">
  <h2>{{ title }}</h2>
  <p>{{ date | localdate }}</p>
  {% if location %}<p>Location: {{ location }}</p>{% endif %}
  {% if description %}<p>{{ description }}</p>{% endif %}
  <img src="{{ event_url | qrcode }}" width="150" />
</div>

Typst Invoice

#set page(paper: "letter", margin: 2cm)
#set text(font: "Inter", size: 10pt)

= Invoice {{ invoice_number }}

*Date:* {{ date | dddd }}
*Due:* {{ due_date | dddd }}

#table(
  columns: (1fr, auto, auto, auto),
  [*Item*], [*Qty*], [*Price*], [*Total*],
  {% for item in line_items %}
  [{{ item.name }}], [{{ item.qty }}], [${{ item.price }}], [${{ item.total }}],
  {% endfor %}
)

#align(right)[*Total: ${{ total }}*]

ECharts Visualization

{
  "xAxis": { "type": "category" },
  "yAxis": { "type": "value" },
  "series": [{
    "type": "bar",
    "data": "$fn:group_count(invoices, status, 10)",
    "itemStyle": { "color": "#4472C4" }
  }],
  "tooltip": { "trigger": "axis" }
}

Composable Template (HTML embedding a chart and table)

<h1>{{ title }}</h1>

<div class="chart">
  {{ "sales-chart" | render_chart("svg", 800, 400) }}
</div>

<h2>Details</h2>
{{ rows | to_md_table(["product", "revenue", "units"]) }}

<footer>Generated {{ "" | timestamp }}</footer>