Skip to content

Template context

One context serves both the question engine and the renderer. A value resolved while prompting is the same value the template sees.

Shape

flowchart LR
    accTitle: Template context namespaces
    answers("Answers") --> top("Top level, by name")
    computed("Computed values") --> top
    data("Data sources") --> data_namespace("Under data")
    template("Template metadata") --> template_namespace("Under template")
{{ project_name }}          {# an answer #}
{{ package_name }}          {# a computed value #}
{{ data.licenses.mit.spdx }} {# loaded data #}
{{ template.name }}          {# template metadata #}

Why answers are at the top level

Because {{ answers.project_name }} is noise, and templates are read far more often than they are written. The cost is that answers and computed values share one namespace — which is why a collision between them is an error rather than a shadow.

data and template are namespaced because they are structured and are not what a template reaches for most of the time.

template

Name Type
template.name string
template.description string or undefined

Deliberately minimal. The template's revision is not here: a template that rendered its own commit SHA into a file would produce a different tree on every template commit, which is exactly the non-determinism this design avoids. The revision is recorded in the commit trailers instead, where it belongs.

data

Whatever the data sources parsed to, as structured values — tables stay tables, arrays stay arrays, numbers stay numbers. See Data sources.

Null and absence

JSON/YAML null and a whole expression returning none preserve an explicit null value, including inside containers. Null is defined and falsy; it is distinct from a missing name, false, zero and an empty string. Use value is defined for presence and value is none for null. The JSON context dump retains null-valued members and omits missing names.

This changes older null-to-empty-string normalization. If a template needs empty text for null, choose it explicitly, for example {{ value if value is not none else '' }}. Undefined expression results retain their existing lenient empty-string conversion; undefined is not null. Question types remain non-nullable, and TOML has no native null literal. See context test assertions and ADR-048.

How it is built

flowchart TD
    accTitle: One context for prompting and rendering
    accDescr: The question engine resolves values in dependency order; prompting and MiniJinja share the same context.
    revision("Template revision") --> local("Local data sources")
    revision --> remote("Remote data sources")
    local --> initial("Initial context")
    remote --> initial
    initial --> engine("Question engine: topologically ordered")
    engine --> answers("Answers")
    engine --> computed("Computed values")
    engine --> conditions("Conditions")
    answers --> context("Resolved context")
    computed --> context
    conditions --> context
    context --> prompting("Prompting")
    context --> rendering("MiniJinja")

There is no second pass and no second context. The renderer receives exactly what the last question saw.

What is not in it

No environment variables. No current time. No Git user. No repository metadata. No process state.

This is not an omission. A value that varies by machine belongs in the answers, where it is recorded and shared — not in the context, where it is invisible and different for everyone.

The one place a machine fact is legible to a template is default_from, which reads its own small seed context — the Git configuration, the directory name, the remote. That context is not this one, is reachable from nowhere else, and only ever pre-fills a prompt.

Imported names

A {% import %} brings a shared partial's macros into scope for the file that imports it, and for that file only. Nothing is implicitly available: a macro must be imported where it is used.

{% import "macros.jinja" as m %}
{{ m.badge(project_name) }}

A partial is any .jinja file outside the rendered subdirectory, named by its path from the repository root. It is read from the same pinned template revision as everything else — the loader cannot name a path on your machine.

The same imports work in manifest expressions, so a computed value can use the macros a file uses.

Filters and functions

MiniJinja's built-in filters are available: lower, upper, replace, trim, join, default, length, first, last, sort, map, select, tojson, and the rest.

No custom functions are registered. Anything that would reach outside the context — reading a file, making a request, running a command — is not, and will not be, available to expressions. Fetching belongs to the data-source subsystem, which owns it explicitly.

slugify

One filter is added to the built-ins, because it is the one a real template cannot write for itself:

{{ project_name | slugify }}

It transliterates to ASCII, lowercases, and joins the remaining alphanumeric runs with a single -:

Input Result
My Project my-project
Hello, World! hello-world
Café Déjà-Vu cafe-deja-vu
Größe grosse
Москва moskva
北京 bei-jing

lower | replace(' ', '-') is the usual substitute and it is wrong twice: it leaves accents and punctuation in the result, and it produces something that is not a valid module name, package name or path segment for anyone whose project is not named in ASCII.

Input that slugs to nothing — !!!, or an empty string — yields an empty string rather than an error. A filter that raised inside a when condition would abort the whole render; an empty value is visible immediately.

The filter is available everywhere any other expression is: in a default, in a when, in a computed value, in a file body, in a templated path, and in a default_from seed expression — which is where {{ remote.name | slugify }} earns its keep.

The set of filters is closed. There is no plugin point, and there will not be one — see ADR-003. A filter is only considered if it is pure, deterministic, and reaches nothing outside its own argument, and every one added is a compatibility surface that cannot later be removed.