Common gotchas

Types

Types are preserved in Jinja2 expressions. This means that any numeric values that are used in an arithmetic expression must not be in quotes, or must be cast using a filter like {{ x|float / 7 }}.

Expressions

When putting expressions in variables, they must be encased in quotes to ensure they are treated as strings. For example:

# Illegal
foo: {{ bar }}
# Legal
foo: "{{ bar }}"

Filter Operator Precedence

The filter operator | has extremely high precedence (like a bitwise or), so take that into account when designing expressions. For example, {{ (a|float) / 2 + (b|float) / 2 | int }} won't do as you expect. You can write this as {{ ((a|float) / 2 + (b|float) / 2) | int }}, but it's better to let operator precedence do its job and write {{ (a|float / 2 + b|float / 2)|int }}. I like to leave out the spaces between filter operands to remind myself of its high precedence.

YAML Anchoring

The yaml config anchoring method of configuration is on a per-theme basis. That is, if your defaults.yaml has an anchor, it does not alter to reflect a change in the anchored variable in a variable_sets theme yaml. An example of anchors is as follows:

font:  &font "foo"
samefont:  *font

If you use another yaml in which font has a different value, the samefont variable will still fall back to foo, rather than whatever font is defined as in your theme. The simplest workaround for this would be to use the {{ ... }} templating syntax to set samefont consistently to whatever font is or to use the anchors in all instances of the redefinition of these variables.