---
title: Why existing AsciiDoc converters lose your structure
description: Asciidoctor, DocBook and downdoc all resolve preprocessing away. The output compiles — and the modular logic that made the corpus maintainable is gone.
created: "2026-08-17"
author: Gabriel McGoldrick
tags:
  - topic/asciidoc
  - topic/migration
---

# Why existing AsciiDoc converters lose your structure {#why-existing-asciidoc-converters-lose-your-structure}

Every established route from AsciiDoc to Markdown has the same failure mode: it *executes* the preprocessing instead of *translating* it.

:::note{title="AsciiDoc to Markdown — part 2 of 7"}
1. [Migrating AsciiDoc to Markdown](/blog/migrating-asciidoc-to-markdown/)
2. **Why existing AsciiDoc converters lose your structure** — you are here
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/)
:::

## Using Asciidoctor {#using-asciidoctor}

When you compile AsciiDoc source natively to an Abstract Syntax Tree using Asciidoctor, all preprocessor instructions like `ifdef::`, `ifndef::`, variables, and `include::` are fully executed, stripped away and resolved into plain static text.

That completely loses the original logic. Variable references, dynamic conditionals and sub-file links disappear entirely.

## Using DocBook XML {#using-docbook-xml}

You can convert AsciiDoc to DocBook XML with Asciidoctor, then convert that XML to Markdown with [Pandoc](https://pandoc.org/) or custom XSLT.

The extra hop changes nothing that matters. The resulting Markdown suffers the same loss of semantics, because the preprocessing was already resolved before the XML existed.

## Using downdoc {#using-downdoc}

[downdoc](https://github.com/opendevise/downdoc), from OpenDevise, is a fast CLI tool that maps AsciiDoc syntax directly to Markdown without a full Asciidoctor compilation.

It resolves variables and conditionals rather than trying to maintain the semantic intent, and it drops or resolves `include::` references, losing the essential structure of your files.

## The common thread {#the-common-thread}

None of these converters take a holistic approach. They work file by file, destroying whatever modular structure you had in place.

For a corpus of a few dozen standalone pages, that is fine. For a corpus where one source file serves multiple products, and hundreds of modules are assembled into books, it means your migration requires a lot of rework and maybe even a rewrite.

Next: [why Jinja is the right target](/blog/why-jinja-is-the-right-target/).