godtpl

godtpl

A Go package for generating OpenDocument Text (.odt) files using Go's standard text/template engine.

English | 繁體中文

[!WARNING] This project was developed with AI assistance (Vibe Coding). The code has not been fully reviewed by a human and may contain bugs, security vulnerabilities, or unexpected behavior. Do not use in production environments. Use at your own risk. Issues and PRs to improve the project are welcome.

Overview

godtpl lets you create .odt documents by writing them as Go templates in LibreOffice Writer (or any ODT-compatible editor), then rendering them with data at runtime. It handles the XML patching needed to work around how editors fragment template tags across multiple XML elements.

Features

• Use standard Go text/template syntax inside ODT files
• Loop over table rows, paragraphs, and inline spans
• Rich text formatting (bold, italic, color, font size, etc.)
• Multi-line text with newlines, tabs, and paragraph breaks
• Embed inline images
• Embed sub-documents (merge multiple ODT files)
• No external dependencies — standard library only

Installation

go get github.com/scbmark/godtpl

Quick Start

1. Create a template in LibreOffice Writer with placeholders like {{ .name }}, save it as template.odt.
2. Render it from Go:

package main

import (
    "github.com/scbmark/godtpl"
    "log"
)

func main() {
    tpl, err := godtpl.New("template.odt")
    if err != nil {
        log.Fatal(err)
    }

    err = tpl.Render(map[string]any{
        "company": "ACME Corp",
        "year":    2024,
    })
    if err != nil {
        log.Fatal(err)
    }

    err = tpl.SaveTo("output.odt")
    if err != nil {
        log.Fatal(err)
    }
}

Template Syntax

Templates use standard Go text/template syntax. Write directly inside your ODT document.

Variable substitution

{{ .name }}
{{ .address }}
{{ .order.total }}        {{/* nested field / map key access */}}

Template variables

Declare local variables with :=:

{{ $label := .firstName }}
Hello, {{ $label }}!

{{ $count := len .items }}
Total: {{ $count }}

Conditionals

{{ if .isPremium }}Premium customer{{ end }}

{{ if .isPremium }}
  Premium
{{ else }}
  Standard
{{ end }}

{{ if gt .score 90 }}Excellent{{ else if gt .score 60 }}Pass{{ else }}Fail{{ end }}

Loops

Loop over a slice

{{ range .items }}
  {{ .name }}: {{ .price }}
{{ end }}

Access the loop index with $i:

{{ range $i, $item := .items }}
  {{ $i }}: {{ $item.name }}
{{ end }}

Loop over a map (map[string]string / map[string]any)

Pass a map value in your context:

err = tpl.Render(map[string]any{
    "attrs": map[string]string{
        "color": "red",
        "size":  "large",
    },
})

Then iterate over it in the template:

{{ range $key, $value := .attrs }}
  {{ $key }}: {{ $value }}
{{ end }}

Keys are iterated in alphabetical order (Go's standard map range behaviour).

Loop over ODT table rows / paragraphs / spans

For looping over table rows, paragraphs, or inline spans, use shorthand prefixes to strip the surrounding ODT XML element:

In your ODT table, put the loop control in the first cell of a row:

{%tr range .items %}  {%tr end %}

The row element itself is stripped; only the template statement remains.

Combining with map range:

{%tr range $key, $value := .attrs %}
  (first cell) {{ $key }}   (second cell) {{ $value }}
{%tr end %}

Escaping literal {{ and }}

If you need literal braces in output, use the escape sequences:

Built-in template functions

{{ xml_escape .userInput }}

API Reference

Loading a template

// From a file path
tpl, err := godtpl.New("template.odt")

// From an io.Reader
tpl, err := godtpl.NewFromReader(r)

Rendering and saving

// Render with a context map
err = tpl.Render(map[string]any{ ... })

// Save to a file
err = tpl.SaveTo("output.odt")

// Save to an io.Writer
err = tpl.Save(w)

The same Template instance can be rendered multiple times with different contexts.

Multi-line text — Listing

Listing handles newlines and special characters inside a single ODT text node.

listing := godtpl.NewListing("Line one\nLine two\nLine three")

Use in template:

{{ .description }}

where ctx["description"] = godtpl.NewListing("...").

Rich text — RichText / R

RichText (alias R) builds inline-formatted text programmatically.

rt := godtpl.NewRichText(tpl)
rt.Add("Hello ", godtpl.TextProps{Bold: true})
rt.Add("world", godtpl.TextProps{Color: "#FF0000", Size: 14})
rt.AddStyled("Important", "Emphasis")  // use a named style from the ODT

TextProps fields:

ctx["title"] = rt

Rich text paragraphs — RichTextParagraph / RP

RichTextParagraph (alias RP) builds block-level paragraphs with optional paragraph styles.

rp := godtpl.NewRichTextParagraph(tpl)
rp.Add(rt, "Heading_20_2")  // second arg is an optional paragraph style name
rp.Add(rt2, "")             // no paragraph style

Inline images — InlineImage

// From a file
img, err := godtpl.NewInlineImage(tpl, "logo.png")

// From an io.Reader
img, err := godtpl.NewInlineImageFromReader(tpl, r, "png")

img.Width  = "4cm"
img.Height = "2cm"

{{ .logo }}

Supported formats: PNG, JPG, GIF, BMP, SVG, TIFF, WEBP.

Sub-documents — Subdoc

Embed a separate ODT file inside the output document.

sd, err := tpl.NewSubdoc("chapter.odt")
ctx["chapter"] = sd

{{p .chapter }}

Styles from sub-documents are automatically prefixed to avoid name collisions.

Requirements

• Go 1.21+
• No external dependencies

License

MIT