Go Templates

Overview

gpdf integrates with Go's text/template package for dynamic content generation. Templates produce JSON schema output that gpdf renders as PDF.

Two approaches are available:

FromJSON — Inline Go template expressions in JSON (simpler)
FromTemplate — Pre-parsed Go template for full control (flexible)

FromJSON with Template Expressions

The simpler approach — embed Go template expressions directly in JSON:

schema := []byte(`{
    "page": {"size": "A4", "margins": "20mm"},
    "metadata": {"title": "{{.Title}}"},
    "body": [
        {"row": {"cols": [
            {"span": 12, "text": "{{.Title}}", "style": {"size": 24, "bold": true}}
        ]}},
        {"row": {"cols": [
            {"span": 12, "text": "Author: {{.Author}}"}
        ]}}
    ]
}`)

doc, err := template.FromJSON(schema, map[string]any{
    "Title":  "Monthly Report",
    "Author": "ACME Corp",
})

FromTemplate with Pre-Parsed Templates

For complex logic like loops and conditionals, use FromTemplate:

import (
    gotemplate "text/template"
    "github.com/gpdf-dev/gpdf/template"
)

tmplStr := `{
    "page": {"size": "A4", "margins": "20mm"},
    "metadata": {"title": "{{.Title}}"},
    "body": [
        {"row": {"cols": [
            {"span": 12, "text": "{{.Title}}", "style": {"size": 24, "bold": true}}
        ]}},
        {"row": {"cols": [
            {"span": 12, "spacer": "5mm"}
        ]}},
        {{- range $i, $section := .Sections}}
        {{- if $i}},{{end}}
        {"row": {"cols": [
            {"span": 12, "elements": [
                {"type": "text", "content": "{{$section.Heading}}", "style": {"size": 16, "bold": true, "color": "#1A237E"}},
                {"type": "spacer", "height": "3mm"},
                {"type": "text", "content": "{{$section.Body}}"},
                {"type": "spacer", "height": "8mm"}
            ]}
        ]}}
        {{- end}}
    ]
}`

tmpl, err := gotemplate.New("report").Funcs(template.TemplateFuncMap()).Parse(tmplStr)
if err != nil {
    log.Fatal(err)
}

type section struct {
    Heading string
    Body    string
}

data := map[string]any{
    "Title": "Quarterly Report - Q1 2026",
    "Sections": []section{
        {
            Heading: "Executive Summary",
            Body:    "Revenue increased 25% year-over-year, driven by new enterprise offerings.",
        },
        {
            Heading: "Product Development",
            Body:    "The gpdf library reached v0.8 with JSON schema and Go template support.",
        },
        {
            Heading: "Market Analysis",
            Body:    "PDF generation market grows. Zero-dependency approach resonates with Go devs.",
        },
        {
            Heading: "Next Steps",
            Body:    "Focus on reusable components, fuzz testing, and v1.0 release.",
        },
    },
}

doc, err := template.FromTemplate(tmpl, data)
if err != nil {
    log.Fatal(err)
}
pdfData, err := doc.Generate()

┌─ A4 ──────────────────────────────────────────────┐
│                                                   │
│  Quarterly Report - Q1 2026      ← 24pt bold      │
│                                                   │
│  Executive Summary               ← 16pt bold blue │
│  Revenue increased 25% year-over-year, driven     │
│  by new enterprise offerings.                     │
│                                                   │
│  Product Development                              │
│  The gpdf library reached v0.8 with JSON schema   │
│  and Go template support.                         │
│                                                   │
│  Market Analysis                                  │
│  PDF generation market grows. Zero-dependency     │
│  approach resonates with Go devs.                 │
│                                                   │
│  Next Steps                                       │
│  Focus on reusable components, fuzz testing,      │
│  and v1.0 release.                                │
│                                                   │
└───────────────────────────────────────────────────┘

Template Function Map

Use TemplateFuncMap() when parsing templates — it provides helper functions:

tmpl, err := gotemplate.New("doc").Funcs(template.TemplateFuncMap()).Parse(tmplStr)

Available Functions

Function	Description
`toJSON`	Converts a Go value to JSON string (useful for embedding data)

Dynamic Sections with Range

Loop over data to generate repeated sections:

{{- range $i, $item := .Items}}
{{- if $i}},{{end}}
{"row": {"cols": [
    {"span": 6, "text": "{{$item.Name}}"},
    {"span": 6, "text": "{{$item.Value}}", "style": {"align": "right"}}
]}}
{{- end}}

Conditionals

Use if for conditional content:

{{- if .ShowHeader}}
{"row": {"cols": [
    {"span": 12, "text": "{{.HeaderText}}", "style": {"size": 20, "bold": true}}
]}},
{{- end}}

Tips

Use {{- and -}} to trim whitespace around template actions
Handle JSON commas carefully in range loops (use {{if $i}},{{end}})
Use TemplateFuncMap() to get built-in helper functions
Go options (WithFont, WithMargins, etc.) can override template settings:

doc, err := template.FromTemplate(tmpl, data,
    template.WithFont("NotoSansJP", fontData),
    template.WithDefaultFont("NotoSansJP", 12),
)