How to Use Template Variables

Note: Template variables are a content substitution system ({{variable}} placeholders) — they are unrelated to themes, which control visual styling (colors, fonts, layouts). For theme documentation, see Themes.

Template variables let you create reusable decks with {{variable}} placeholders that get filled in at render time. This is useful for recurring presentations — weekly standups, personalized sales proposals, quarterly reviews — where the structure stays the same but the data changes.

Define default values in frontmatter

Set defaults in the agentpreso.vars block:

---
agentpreso:
  theme: corporate
  vars:
    company: "Acme Corp"
    deal_size: "$500K"
    quarter: "Q3 2025"
---

# Partnership Proposal
## {{company}} × Our Product

- **Deal Size**: {{deal_size}}
- **Timeline**: {{quarter}}

If you render this deck without overriding anything, it uses the defaults: “Acme Corp”, “$500K”, “Q3 2025”.

Override variables at render time

CLI — from a YAML or JSON file

Create a data file:

# contoso-data.yaml
company: "Contoso Ltd"
deal_size: "$1.2M"
quarter: "Q4 2025"

Render with it:

agentpreso render proposal.md --vars contoso-data.yaml

CLI — inline overrides

agentpreso render proposal.md --var company="Contoso" --var deal_size="\$1.2M"

Inline --var flags override file values. Combine both:

agentpreso render proposal.md --vars defaults.yaml --var company="Override Inc"

API

Pass vars in the render request body:

{
  "markdown": "...",
  "format": "pdf",
  "vars": {
    "company": "Contoso Ltd",
    "deal_size": "$1.2M"
  }
}

MCP

Pass vars to render_deck:

{
  "tool": "render_deck",
  "arguments": {
    "deckId": "deck-abc123",
    "format": "pdf",
    "vars": {
      "company": "Contoso Ltd",
      "deal_size": "$1.2M"
    }
  }
}

Use variables in charts

Variables work inside chart blocks — supply data as arrays:

```chart
type: bar
data:
  labels: {{quarter_labels}}
  datasets:
    - label: Revenue ($M)
      data: {{revenue_data}}
```

Supply the arrays when rendering:

# data.yaml
quarter_labels: ["Q1", "Q2", "Q3", "Q4"]
revenue_data: [4.2, 5.1, 6.3, 7.8]
agentpreso render deck.md --vars data.yaml

Arrays are serialized as JSON in the output, which chart blocks parse natively.

Use variables in diagrams

Variables also work inside mermaid and excalidraw blocks:

```mermaid
graph LR
    A[{{source_system}}] --> B[{{target_system}}]
```

Use dot notation for nested data

Access nested values with dot notation:

Contact: {{contact.name}} ({{contact.email}})
# data.yaml
contact:
  name: "Jane Smith"
  email: "[email protected]"

Merge priority

Variables merge in this order (later wins):

  1. Frontmatter agentpreso.vars defaults (lowest priority)
  2. --vars file values
  3. --var inline overrides / API vars object / MCP vars (highest priority)

Variable rules

  • Frontmatter is never modified — {{var}} inside the --- block is not substituted
  • Regular code blocks are skipped — {{var}} inside fenced code blocks is preserved as literal text
  • Chart, mermaid, and excalidraw blocks ARE substituted — these are data blocks, not code
  • Inline code is skipped — `{{var}}` stays as-is
  • Dot notation — {{metrics.revenue}} traverses nested objects
  • No expressions — only simple key lookup, no {{a + b}} or {{#if}}
  • Escape with backslash — \{{literal}} renders as {{literal}} in the output
  • Unresolved variables — if a key isn’t found, {{name}} stays as-is in the output
  • No recursive expansion — if a variable’s value contains {{x}}, it is not expanded again
  • Supported types — strings, numbers, booleans, arrays (serialized as JSON)