pongo2 Documentation

Manipulate how content is rendered and escaped.

• {% autoescape on|off %} / {% endautoescape %}: Controls automatic HTML escaping.
• {% filter filter_name %} / {% endfilter %}: Applies one or more filters to an entire block of content.
• {% spaceless %} / {% endspaceless %}: Removes whitespace between HTML tags.
• {% verbatim %} / {% endverbatim %}: Outputs content without processing any template syntax (useful for client-side frameworks like Vue or Angular).
• {% comment %} / {% endcomment %}: Multi-line comments that are not rendered.

{% verbatim %}
  {{ this_will_not_be_processed }}
{% endverbatim %}

Macros are reusable template fragments that act like functions. They accept arguments, can have default values, and return rendered content. Use the {% macro %} tag to define them and {{ }} to call them.

Syntax:

{% macro name(arg1, arg2, ...) %}
  ...content...
{% endmacro %}

Calling:

{{ macro_name("arg_value") }}

{% macro button(text, url) %}
  <a href="{{ url }}" class="btn">{{ text }}</a>
{% endmacro %}

{{ button("Click Me", "/home") }}

A custom tag requires two components:

1. Tag Parser Function: Parses the tag syntax at compile time.
2. Tag Node: Executes the tag logic at render time.

The parser function must match the TagParser signature, and the resulting node must implement the INodeTag interface, which includes an Execute method.

// Tag parser function signature
type TagParser func(doc *Parser, start *Token, arguments *Parser) (INodeTag, error)

// Tag node must implement INodeTag (which extends INode)
type INodeTag interface {
    Execute(ctx *ExecutionContext, writer TemplateWriter) error
}

During the execution phase of a tag, use the ExecutionContext.Error(msg, token) method to report runtime issues (e.g., invalid values or nil pointers). To wrap an existing Go error with template position information, use ctx.OrigError(err, token).

func (node *myNode) Execute(ctx *pongo2.ExecutionContext, writer pongo2.TemplateWriter) error {
    val, err := node.expr.Evaluate(ctx)
    if err != nil {
        return err
    }

    if val.IsNil() {
        return ctx.Error("value cannot be nil", node.position)
    }

    if val.Integer() < 0 {
        return ctx.Error("value must be non-negative", node.position)
    }

    return nil
}

// Wrapping an existing error
if err != nil {
    return ctx.OrigError(err, node.position)
}

To create iteration tags (like {% each item in items %}), you must manage a child context for each iteration. Use pongo2.NewChildExecutionContext(ctx) to create a new context, then populate its Private map with the loop variable and loop metadata (e.g., eachloop).

Loop metadata structure example:

type eachLoop struct {
    Counter     int
    Counter0    int
    First       bool
    Last        bool
    Revcounter  int
    Revcounter0 int
}

To prevent SSTI, never concatenate user input directly into the template string. Instead, use placeholders in the template and pass the user input via the pongo2.Context during execution.

// SAFE
tpl, _ := pongo2.FromString("Hello {{ name }}!")
tpl.Execute(pongo2.Context{"name": userInput})

Access helper functions for common template tasks.

• {% now "format" %}: Outputs the current date/time using Go's time format strings (e.g., {% now "2006-01-02" %}).
• {% lorem %}: Generates placeholder text.
  • {% lorem 3 %}: 3 paragraphs.
  • {% lorem 5 w %}: 5 words.
  • {% lorem 2 p %}: 2 HTML paragraphs.
• {% widthratio value max width %}: Calculates a ratio for UI elements like progress bars. Formula: (value / max_value) * max_width.
• {% templatetag name %}: Outputs template syntax characters like {% templatetag openblock %} (outputs {%).

<div style="width: {% widthratio current_value max_value 100 %}px;"></div>

pongo2 uses Go's time formatting and fmt.Sprintf logic instead of Python/Django defaults.

Date Formatting: Use the |date filter with Go's reference time (2006-01-02).

• {{ now|date:"2006-01-02" }}
• {{ now|date:"Monday, January 2, 2006" }}

String Formatting: Use the |stringformat filter with Go's fmt.Sprintf verbs.

• {{ 3.14159|stringformat:"%.2f" }}

{{ now|date:"2006-01-02" }}
{{ now|time:"15:04:05" }}
{{ 3.14159|stringformat:"%.2f" }}
{{ 42|stringformat:"%05d" }}

To secure a template set (especially when handling user-provided templates), you can ban specific tags and filters.

CRITICAL: You must call BanTag or BanFilter BEFORE loading any templates into the set. Once the first template is loaded, the set is locked, and attempting to ban items will return an error.

Commonly banned items for security:

• set.BanTag("include"): Prevents file inclusion.
• set.BanTag("ssi"): Prevents server-side includes.
• set.BanFilter("safe"): Prevents users from bypassing autoescape.

set := pongo2.NewSet("restricted", loader)

// Ban dangerous tags BEFORE loading templates
set.BanTag("include")
set.BanTag("ssi")
set.BanFilter("safe")

// Now it is safe to load templates
tpl, err := set.FromFile("user-content.html")

By default, macros are only available in the template where they are defined. To use them in other templates, you must mark them with the export keyword immediately after the argument list.

To use exported macros, use the {% import %} tag.

Import Syntax: {% import "filename" macro1, macro2 %}

Aliasing: You can rename imported macros using the as keyword to avoid name conflicts or create shorter names. {% import "filename" macro_name as alias %}