Mapping AsciiDoc ifeval to Jinja¶

Jinja maps AsciiDoc ifeval:: directly, using equality comparisons of the form {% if x == y %}.

The OpenShift docs use tight coupling between parent and child AsciiDoc documents. A module asks which assembly am I being included from? and adapts. That is replicable in Markdown with Jinja.

Setting a flag from context¶

• AsciiDoc:
  asciidoc

  ifeval::["{context}" == "changing-cloud-credentials-configuration"]
  :postinstall:
  endif::[]

• Jinja:
  jinja

  {%- if context == "changing-cloud-credentials-configuration" %}
  {%- set postinstall = true -%}
  {% endif %}

Unsetting it again¶

This is the part that is easy to miss. Because AsciiDoc attributes persist once set, a module that sets a flag must also clear it — otherwise the flag leaks into every document assembled afterwards. The same discipline is required in the Jinja form:

• AsciiDoc:
  asciidoc

  ifeval::["{context}" == "changing-cloud-credentials-configuration"]
  :!postinstall:
  endif::[]
  ifeval::["{context}" == "preparing-manual-creds-update"]
  :!update:
  endif::[]

• Jinja:
  jinja

  {%- if context == "changing-cloud-credentials-configuration" %}
  {%- set postinstall = false -%}
  {% endif %}
  {% if context == "preparing-manual-creds-update" %}
  {%- set update = false -%}
  {% endif %}

Note :!postinstall: — the ! is AsciiDoc's unset, and it becomes set ... = false, not a deletion. A converter that silently drops the unset produces documents that are correct in isolation and wrong in sequence, which is the hardest class of bug to spot in a migrated corpus.

Reference: Configuring the Cloud Credential Operator utility

Next: mapping AsciiDoc includes and level offsets to Jinja.