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.
- Migrating AsciiDoc to Markdown
- Why existing AsciiDoc converters lose your structure — you are here
- Why Jinja is the right target
- Mapping AsciiDoc variables to Jinja
- Mapping AsciiDoc conditionals to Jinja
- Mapping AsciiDoc ifeval to Jinja
- Mapping AsciiDoc includes and level offsets to Jinja
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
You can convert AsciiDoc to DocBook XML with Asciidoctor, then convert that XML to Markdown with Pandoc 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
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
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.