Migrating AsciiDoc to Markdown¶

AsciiDoc has a number of features that do not naturally migrate to Markdown. The DogsBay conversion is a two-stage process: core pre-processing features in AsciiDoc are mapped to equivalent pre-processing functionality in the Jinja templating language, which is then rendered to produce the final Markdown.

What AsciiDoc gives you that Markdown does not¶

AsciiDoc started out as a plain-text alternative to the complex DocBook XML syntax — literally, the name is derived from an Ascii version of DocBook. On top of the core DocBook features, it added a number of useful features for creating reusable modular documentation:

• Global variables, which can also be redefined on the fly
• Conditionals such as ifdef::, ifndef:: and ifeval::, driven by those global variables
• Modular, reusable content via include:: directives, with level offsets to handle nested titles
• Complex table syntax supporting column and row spans, alignment and widths, and embedded blocks

Why migrations go wrong¶

If you are migrating from AsciiDoc to Markdown, you want to keep the semantic intent of your documentation.

A modular AsciiDoc corpus is not a folder of complete pages. It is a set of fragments and assembly instructions that can produce different output for each audience and version. Existing migration tools lose all the modular discipline you have instilled in your writing.

The two-step conversion¶

1. Translation — rewrite each AsciiDoc directive with its Jinja equivalent:
   • Variables: {name} becomes {{ name }}
   • Conditionals: ifdef:: becomes {% if %}
   • Modular docs: include:: becomes {% include %}
2. Rendering — resolve the variables, conditionals and includes to produce the final Markdown for each specific variant.

The translation step is the one that matters. It is what keeps a conditional a conditional, rather than baking one audience's version into the output and deleting the rest.