---
title: Mapping AsciiDoc variables to Jinja
description: Attribute definitions become Jinja set statements, references become expressions — with one naming rule you have to apply, because hyphens mean subtraction.
created: "2026-08-19"
author: Gabriel McGoldrick
tags:
  - topic/asciidoc
  - topic/jinja
---

# Mapping AsciiDoc variables to Jinja {#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.

:::note{title="AsciiDoc to Markdown — part 4 of 7"}
1. [Migrating AsciiDoc to Markdown](/blog/migrating-asciidoc-to-markdown/)
2. [Why existing AsciiDoc converters lose your structure](/blog/why-existing-converters-lose-structure/)
3. [Why Jinja is the right target](/blog/why-jinja-is-the-right-target/)
4. **Mapping AsciiDoc variables to Jinja** — you are here
5. [Mapping AsciiDoc conditionals to Jinja](/blog/asciidoc-conditionals-in-jinja/)
6. [Mapping AsciiDoc ifeval to Jinja](/blog/asciidoc-ifeval-in-jinja/)
7. [Mapping AsciiDoc includes and level offsets to Jinja](/blog/asciidoc-includes-in-jinja/)
:::

## The one naming rule {#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 {#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 {#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 {#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](https://raw.githubusercontent.com/openshift/openshift-docs/refs/heads/main/welcome/index.adoc)

Next: [mapping AsciiDoc conditionals to Jinja](/blog/asciidoc-conditionals-in-jinja/).