Why Jinja is the right target¶

The key idea behind the DogsBay AsciiDoc to Markdown conversion is keeping the structure of your documentation identical, using Jinja templates to express the features that other converters throw away.

What Jinja is¶

Jinja is a fast, expressive and highly extensible templating engine, originally for Python and based on the Django template syntax. It generates text-based files — HTML, XML, Markdown, configuration — by mixing static boilerplate with dynamic variables and logic.

Why not something bespoke¶

Jinja's syntax is popular enough to have been ported well beyond Python — Twig in PHP, Nunjucks in JavaScript — and it is used far outside web development:

• Infrastructure as code: Ansible uses Jinja to inject environment variables into server configuration playbooks.
• Data engineering: dbt embeds Jinja directly inside SQL to loop over date ranges, switch environments and abstract schema transformations.

Choosing an established templating language means the intermediate form is something your team can already read, and something other tools can already process.

The syntax that matters¶

Three constructs carry the whole conversion:

• Expressions {{ ... }} output the result of a variable or expression.
  html

  <h1>Hello, {{ user.name }}!</h1>

• Statements {% ... %} control logic and flow — conditionals, loops, inheritance.
  html

  {% if user.is_logged_in %}
    <p>Welcome back!</p>
  {% else %}
    <p>Please log in.</p>
  {% endif %}

• Includes {% include ... %} pull a snippet into that exact spot.
  html

  {% include 'fragments/header.html' %}

Those three map onto AsciiDoc's variables, conditionals and include:: directives almost one for one. The next four posts work through each mapping against real OpenShift source.

Next: mapping AsciiDoc variables to Jinja.