Mapping AsciiDoc variables to Jinja
The samples here are taken from the OpenShift documentation, currently a contender for the most complex AsciiDoc corpus openly available.
The one naming rule
Jinja variable names cannot contain a hyphen — it is interpreted as a minus sign in an expression. DogsBay converts hyphens in variable names to underscores, so product-title becomes product_title.
This is worth internalising before you read any of the other mappings, because every variable in a real corpus is hyphenated.
Setting variables
To set a variable in Jinja, use {% ... %}:
- AsciiDoc:asciidoc
:context: welcome-index - Jinja:jinja
{%- set context = "welcome-index" %}
Note that the value keeps its hyphen. Only the variable name is rewritten — values are strings, not identifiers.
Referencing variables
To reference a variable in Jinja, use {{ ... }}:
- AsciiDoc:asciidoc
Welcome to the official {product-title} {product-version} documentation - Jinja:jinja
Welcome to the official {{ product_title }} {{ product_version }} documentation
Why this matters more than it looks
An AsciiDoc attribute can be redefined partway through a document, and often is. Because the translation keeps the variable as a variable, that behaviour survives: the value at render time is still whatever the assembly decided, not whatever it happened to be when the converter ran.
Reference: OpenShift welcome page