Jinja2 Template Engine for Go

A Go implementation of the Jinja2 template engine with comprehensive support for standard features including variables, loops, conditionals, filters, tests, and template inclusion.

Feature Comparison

Comparison with Python's Jinja2 v3.1 template engine:

Feature	Python Jinja2	This Implementation	Notes
Core Syntax
Variable substitution {{ var }}	✅	✅	Full support
Comments {# comment #}	✅	✅	Full support
Control Structures
{% for %} loops	✅	✅	With tuple unpacking
{% if %} conditionals	✅	✅	With elif/else support
{% set %} variables	✅	✅	Full support
{% include %}	✅	✅	Full support
{% extends %} / {% block %}	✅	❌	Not implemented
{% macro %}	✅	❌	Not implemented
{% import %}	✅	❌	Not implemented
Expressions
Arithmetic operators	✅	✅	+, -, *, /, %
Comparison operators	✅	✅	==, !=, <, <=, >, >=
Logical operators	✅	✅	and, or, not
in operator	✅	✅	Full support
Attribute access .	✅	✅	Full support
Index access []	✅	✅	Full support
Filters	60	43	See details
Chained filters	✅	✅	Full support
Custom filters	✅	✅	Full support
Tests	31	16	See details
Negated tests is not	✅	✅	Full support
Custom tests	✅	✅	Full support
Advanced Features
Tuple unpacking in loops	✅	✅	{% for key, value in items %}
Whitespace control	✅	✅	Full support (- modifiers)
Custom delimiters	✅	✅	Full support
Template inheritance	✅	❌	Planned for future
Macros	✅	❌	Planned for future
Auto-escaping	✅	❌	Manual escaping only
Line statements	✅	❌	Not implemented
Loaders
FileSystemLoader	✅	✅	Full support
StringLoader	✅	✅	Full support
PackageLoader	✅	❌	Not needed in Go

Implementation Status

Production Ready:

• Core template rendering with 100% Jinja2 behavioral compatibility
• Variables and expressions
• Control flow (for, if, elif, else, set)
• Tuple unpacking in for loops
• 43 built-in filters (72% of Jinja2)
• 16 built-in tests (52% of Jinja2)
• Template inclusion
• Whitespace control
• Custom delimiters
• Custom filters/tests

Not Implemented:

• Template inheritance (extends/block)
• Macros and imports
• Auto-escaping
• Line statements

This implementation focuses on the most commonly used Jinja2 features, providing clean, efficient, and fully compatible template rendering for Go applications.

Installation

go get github.com/newsamples/jinja2

Quick Start

package main

import (
    "fmt"
    "github.com/newsamples/jinja2"
)

func main() {
    template := "Hello {{ name }}!"
    context := map[string]interface{}{
        "name": "World",
    }

    result, err := jinja2.RenderString(template, context)
    if err != nil {
        panic(err)
    }

    fmt.Println(result)
}

Template Syntax

Variables

{{ variable }}
{{ user.name }}
{{ items[0] }}

Control Structures

For Loop

{% for item in items %}
    {{ item }}
{% endfor %}

For Loop with Tuple Unpacking

{% for key, value in dict | dictsort %}
    {{ key }}: {{ value }}
{% endfor %}

{% for x, y, z in coordinates %}
    Point: ({{ x }}, {{ y }}, {{ z }})
{% endfor %}

If Statement

{% if condition %}
    yes
{% elif other_condition %}
    maybe
{% else %}
    no
{% endif %}

Set Variable

{% set x = 10 %}
{{ x }}

Filters

Filters transform values using the pipe operator:

{{ name | upper }}
{{ items | join(', ') }}
{{ value | default('N/A') }}
{{ users | map('attribute', 'name') | join(', ') }}
{{ numbers | select('even') | join(',') }}

43 built-in filters available (full comparison):

String (13): upper, lower, capitalize, title, trim, replace, escape, forceescape, safe, string, striptags, truncate, wordwrap

List/Sequence (9): join, first, last, length, reverse, list, sort, unique, slice, batch

Numeric (3): abs, int, float

Formatting (4): format, center, indent, wordcount

Filtering/Selection (5): map, select, reject, selectattr, rejectattr

Aggregation (4): sum, min, max, groupby

Data Structure (4): dictsort, items, attr, tojson

Other (1): default

Tests

Tests check conditions using the is keyword:

{% if value is defined %}
    {{ value }}
{% endif %}

{% if num is odd %}
    odd number
{% endif %}

{% if name is string %}
    string value
{% endif %}

16 built-in tests available (full comparison):

Existence/Boolean (6): defined, undefined, none, boolean, true, false

Type (5): number, string, mapping, sequence, iterable

Numeric (3): odd, even, divisibleby

String (2): upper, lower

Operators

Arithmetic

{{ 2 + 3 }}
{{ 10 - 5 }}
{{ 4 * 3 }}
{{ 10 / 2 }}
{{ 10 % 3 }}

Comparison

{{ x == y }}
{{ x != y }}
{{ x < y }}
{{ x <= y }}
{{ x > y }}
{{ x >= y }}

Logical

{{ true and false }}
{{ true or false }}
{{ not false }}
{{ 'a' in items }}

Whitespace Control

Control whitespace with the - modifier:

{%- if true -%}
    No whitespace before or after
{%- endif -%}

Syntax:

• {{- / -}} - Strip whitespace around variable tags
• {%- / -%} - Strip whitespace around block tags
• {#- / -#} - Strip whitespace around comments

Example:

<ul>
{%- for item in items %}
    <li>{{ item }}</li>
{%- endfor %}
</ul>

Advanced Usage

Custom Filters

env := jinja2.NewEnvironment(nil)

env.AddFilter("double", func(value interface{}, args []interface{}) (interface{}, error) {
    if num, ok := value.(int64); ok {
        return num * 2, nil
    }
    return value, nil
})

tmpl, _ := env.FromString("{{ num | double }}")
result, _ := tmpl.Render(map[string]interface{}{"num": int64(5)})
// Output: "10"

Custom Tests

env := jinja2.NewEnvironment(nil)

env.AddTest("positive", func(value interface{}, args []interface{}) (bool, error) {
    if num, ok := value.(int64); ok {
        return num > 0, nil
    }
    return false, nil
})

tmpl, _ := env.FromString("{% if num is positive %}yes{% endif %}")
result, _ := tmpl.Render(map[string]interface{}{"num": int64(5)})
// Output: "yes"

Custom Delimiters

env := jinja2.NewEnvironment(nil)

// Change delimiters to avoid conflicts
env.SetVariableDelimiters("[[", "]]")
env.SetBlockDelimiters("[%", "%]")
env.SetCommentDelimiters("[*", "*]")

tmpl, _ := env.FromString("[% if true %]Hello [[ name ]][% endif %]")
result, _ := tmpl.Render(map[string]interface{}{"name": "World"})
// Output: "Hello World"

Template Loaders

FileSystemLoader

loader := jinja2.NewFileSystemLoader("./templates")
env := jinja2.NewEnvironment(loader)

tmpl, err := env.GetTemplate("base.html")
result, err := tmpl.Render(context)

StringLoader

loader := jinja2.NewStringLoader(map[string]string{
    "base.html": "Hello {{ name }}",
})

env := jinja2.NewEnvironment(loader)
tmpl, err := env.GetTemplate("base.html")

Template Inclusion

{% include "header.html" %}
<main>
    Content here
</main>
{% include "footer.html" %}

Type Handling

The library works with Go types:

• int64 and int for integers
• float64 and float32 for floating-point numbers
• string for strings
• bool for booleans (rendered as True/False)
• []interface{} for arrays
• map[string]interface{} for objects

Type Compatibility Notes

• Numbers: The implementation supports int, int64, float32, float64 for numeric operations and tests
• Booleans: Rendered as capitalized True/False matching Jinja2 behavior
• Sequences: Strings are treated as sequences, consistent with Python Jinja2
• Floats in Tests: Tests like odd, even, and divisibleby accept whole-number floats (e.g., 3.0 is odd)

Examples

Tuple Unpacking with Filters

{% for key, value in dict | dictsort %}
    {{ key }} = {{ value }}
{% endfor %}

{% for key, value in dict | items %}
    {{ key }}: {{ value }}
{% endfor %}

Complex Filtering

{# Get names of users with even age #}
{{ users | selectattr('age', 'even') | map('attribute', 'name') | join(', ') }}

{# Sum prices of active items #}
Total: {{ items | selectattr('active') | sum('price') }}

{# Group items by category #}
{% for group in items | groupby('category') %}
    <h2>{{ group.grouper }}</h2>
    {% for item in group.list %}
        <li>{{ item.name }}</li>
    {% endfor %}
{% endfor %}

String Formatting

{# Truncate and wrap text #}
{{ long_text | truncate(100) | wordwrap(40) }}

{# Center and indent code #}
<pre>{{ code | indent(4, true) }}</pre>

{# Strip HTML tags #}
{{ html_content | striptags }}

Documentation

For detailed filter and test documentation, see:

• Filters and Tests Comparison - Complete list with examples

License

MIT