Mapping AsciiDoc conditionals to Jinja
Esc
Start typing to search...
Gabriel McGoldrick2 min read
On this page

Mapping AsciiDoc conditionals to Jinja

AsciiDoc conditionals and Jinja conditionals express the same idea, so the translation is mostly direct. A templating-based conversion preserves the ability to produce different documents for different audiences.

AsciiDoc to Markdown — part 5 of 7
  1. Migrating AsciiDoc to Markdown
  2. Why existing AsciiDoc converters lose your structure
  3. Why Jinja is the right target
  4. Mapping AsciiDoc variables to Jinja
  5. Mapping AsciiDoc conditionals to Jinja — you are here
  6. Mapping AsciiDoc ifeval to Jinja
  7. Mapping AsciiDoc includes and level offsets to Jinja

Why conditionals exist in the first place

One OpenShift source file can serve several products — Enterprise, OKD, ROSA, Dedicated. Differences can be a sentence or an entire section, and they are encoded with ifdef::. Rendering for Enterprise produces one document. Rendering for OKD produces another, from the same source.

Markdown has no equivalent construct. A conversion that deletes conditionals either merges content for all audiences or keeps one audience and drops the rest. Translating conditionals to {% if %} keeps audience selection as a render-time choice.

The mapping

Jinja maps all AsciiDoc boolean logic directly, using {% if ... %} and {% if not ... %}:

  • AsciiDoc:
    asciidoc
    ifndef::openshift-rosa,openshift-rosa-hcp,openshift-telco[]
Welcome to the official {product-title} {product-version} documentation, where you can learn about {product-title} and start exploring its features.
endif::openshift-rosa,openshift-rosa-hcp,openshift-telco[]
ifdef::openshift-rosa,openshift-rosa-hcp[]
Welcome to the official {product-title} documentation, where you can learn about {product-title} and start exploring its features.
ifdef::openshift-rosa-hcp[]
xref:../rosa_architecture/about-hcp.adoc#about-hcp[{product-title} overview].
endif::openshift-rosa-hcp[]
endif::openshift-rosa,openshift-rosa-hcp[]
  • Jinja:
    jinja
    {%- if not (openshift_rosa or openshift_rosa_hcp or openshift_telco) %}
Welcome to the official {{ product_title }} {{ product_version }} documentation, where you can learn about {{ product_title }} and start exploring its features.
{% endif %}
{% if openshift_rosa or openshift_rosa_hcp %}
Welcome to the official {{ product_title }} documentation, where you can learn about {{ product_title }} and start exploring its features.
{%- if openshift_rosa_hcp %}
[{{ product_title }} overview](../rosa_architecture/about-hcp#about-hcp).
{% endif %}
{% endif %}

Note that the xref: becomes an ordinary Markdown link, and the .adoc extension goes with it.

The inline form

AsciiDoc also has an inline conditional, with content on the same line as the directive. It is often used to give one reused module a context-dependent title:

  • AsciiDoc (modules/cluster-samples-operator.adoc):
    asciidoc
    ifdef::operator-ref[= Cluster Samples Operator]
ifdef::cluster-caps[= OpenShift samples capability]
  • Jinja:
    jinja
    {% if operator_ref %}
# Cluster Samples Operator
{% endif %}
{% if cluster_caps %}
# OpenShift samples capability
{% endif %}

The mapping table

AsciiDocJinja
ifdef::name[]{% if name %}
ifndef::name[]{% if not name %}
endif::[]{% endif %}
a,b,c (comma list)a or b or c (any-of)
a+b+c (plus list)a and b and c (all-of)

The comma and plus lists are the two people get wrong. A comma is or; a plus is and.

Reference: OpenShift welcome page

Next: mapping AsciiDoc ifeval to Jinja.