---
title: Migrating AsciiDoc to Markdown
description: A modular AsciiDoc corpus is not a folder of pages — it is fragments plus assembly instructions. Here is how to move it to Markdown without throwing that away.
created: "2026-08-16"
author: Gabriel McGoldrick
tags:
  - topic/asciidoc
  - topic/migration
---

# Migrating AsciiDoc to Markdown {#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.

:::note{title="AsciiDoc to Markdown — part 1 of 7"}
1. **Migrating AsciiDoc to Markdown** — you are here
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](/blog/asciidoc-variables-in-jinja/)
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/)
:::

## What AsciiDoc gives you that Markdown does not {#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 **Doc**Book. 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 {#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 {#the-two-step-conversion}

:::steps
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.