Why Not Markdown

The short answer is DME-0100. The long answer is on this page. Both are worth reading, but the long answer was written first and the short answer is a link to it.

The structural limitations of Markdown

Markdown is a lightweight markup format optimised for human readability in its raw form. This is a reasonable goal for README files. It is not a sufficient goal for structured technical documentation.

Markdown has no native support for: semantic admonitions, cross-references with validation, attribute substitution, conditional content, or structured section numbering. These are not edge cases. They are the foundation of a maintainable documentation system. Without them, documentation structure is enforced by convention alone. Convention degrades.

AsciiDoc as the correct choice

AsciiDoc provides all of the above. It is more verbose. This is a feature. Verbosity in documentation markup correlates with intentionality. A writer who must explicitly declare NOTE: before a note is a writer who has decided this information is a note. This is not an accident.

Markdown allows the same information to be a paragraph, a blockquote, or bold text depending on mood. WRAAS does not permit mood-dependent documentation structure. Alternative output encodings have been evaluated and rejected on identical grounds (see DME-1337).

Antora's dependency on AsciiDoc

Antora builds structured documentation sites from AsciiDoc sources. It validates xrefs at build time. It enforces component structure. It produces navigable, versioned documentation with a consistent layout. It does not support Markdown source files. This is not an oversight.