Skip to content

Render context data

The result of rendering a template depends on the context in which it is rendered. That is, available variables and their values, and options set on the bound Environment.

Template global variables are those added to a render context by application developers. From a template author's perspective, globals are read-only and are available to all templates, including those rendered with the {% render %} tag.

Template local variables are those defined by template authors using {% assign %} and {% capture %}. Local variables can mask names defined in the global namespace, but never change them.

Named counters created with {% increment %} and {% decrement %} have their own namespace. Outside of increment or decrement, Liquid will look in the counters namespace last, after locals and globals.

Environment globals

The Environment constructor accepts an optional globals argument, which should be a dictionary mapping variable names to their values. These variables get pinned to the environment and will be automatically merged with other variables for every template rendered from that environment.

from liquid2 import Environment

env = Environment(globals={"site_name": "MySite"})

template = env.from_string("""\
<html>
<head>
    <title>{{ site_name }}</title>
</head>
</html>
""")

print(template.render())
output
<html>
<head>
    <title>MySite</title>
</head>
</html>

Template globals

Similar to Environment globals, you can pin global variables to a template when calling from_string() or get_template(). Global variables set on a template will be merged with any set on its environment and added to each render context automatically.

If environment and template globals have conflicting names, template variables take priority over environment variables.

from liquid2 import Environment

env = Environment(globals={"site_name": "MySite"})

source = """\
<html>
<head>
    <title>{{ site_name }} - {{ page.name }}</title>
</head>
</html>
"""

template = env.from_string(source, globals={"page": {"name": "Blog"}})
print(template.render())
output
<html>
<head>
    <title>MySite - Blog</title>
</head>
</html>

Render arguments

Keyword arguments passed to Template.render() are also added to the global namespace, although, unlike environment and template globals, they do not persist between calls to render().

render() keyword arguments take priority over environment and template globals.

from liquid import Environment

env = Environment(globals={"site_name": "MySite"})

source = """\
<html>
    <head>
        <title>{{ site_name }} - {{ page.name }}</title>
    </head>
    <body>
        <p>Hello, {{ user.name }}</p>
    </body>
</html>
"""

template = env.from_string(source, globals={"page": {"name": "Blog"}})
print(template.render(user = {"name": "Sally"}))
output
<html>
    <head>
        <title>MySite - Blog</title>
    </head>
    <body>
        <p>Hello, Sally</p>
    </body>
</html>

Matter

Matter variables are those pinned to a Template by a template loader. They could be from a front matter loader or extra meta data from a database loader.

These, too, are merged into the global namespace, taking priority over template globals, but not render() keyword arguments.