Topic / asciidoc

Two workflows that convert an AsciiBinder AsciiDoc corpus to Markdown and build it as an Astro site, on demand or weekly. Fork them and run them yourself; the OpenShift docs are the test corpus because they are the hardest one.

The same Markdown exported as a Docusaurus 3 project. MDX is stricter than Markdown, definition lists need a plugin, and the base URL has to be split in two. Measured on 1,800 pages and a real build.

The same Markdown that builds the Astro site becomes an MkDocs Material project with one flag. What the exporter maps, what publishing 1,800 pages taught it, and a repo you can fork.

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.

One OpenShift source file serves Enterprise, OKD, ROSA and Dedicated. Translating ifdef to Jinja keeps audience selection a render-time choice instead of baking one variant in.

ifeval couples a parent document to its modules by comparing context strings. Jinja expresses the same coupling — including the unsetting that stops it leaking.

Includes map to Jinja natively. Level offsets do not exist in Jinja at all, so DogsBay extends it — and the extension has to be fence-aware.

Attribute definitions become Jinja set statements, references become expressions — with one naming rule you have to apply, because hyphens mean subtraction.

Asciidoctor, DocBook and downdoc all resolve preprocessing away. The output compiles — and the modular logic that made the corpus maintainable is gone.

AsciiDoc preprocessing and Jinja templating express the same three ideas — variables, conditionals, includes. That correspondence is what makes the conversion faithful.