ADOC converter

Where ADOC comes from

Stuart Rackham created AsciiDoc in 2002 as a Python tool that produced DocBook, filling the gap between writing raw DocBook XML and losing structure to a lightweight syntax. Dan Allen's Asciidoctor, a Ruby reimplementation released in 2013, made it fast and portable and effectively took over the ecosystem. The syntax was finally given a formal specification under the Eclipse Foundation, which is the thing Markdown still lacks: AsciiDoc has one definition, not forty implementations that disagree.

How ADOC works

• Section levels use leading = signs, so a document title is = and a first-level section is ==.
• Document attributes are declared as :name: value lines in the header and can be substituted throughout the body.
• Admonitions (NOTE, TIP, WARNING, CAUTION, IMPORTANT) are first-class syntax rather than a convention.
• include:: directives compose a book from many files — powerful, and the reason untrusted AsciiDoc must never be processed with includes enabled.
• Tables, footnotes, cross-references and source-listing callouts are all specified, so complex documents do not need embedded HTML.

When to use ADOC

• Technical documentation and books where structure matters more than convenience
• Documentation-as-code pipelines that publish HTML and PDF from one source
• Migrating a documentation set to Markdown for a platform that only accepts it
• Extracting readable prose from a documentation repository

Compatibility

GitHub and GitLab render AsciiDoc in repositories; Asciidoctor, IntelliJ, VS Code (via extension) and Antora handle it in toolchains. Novus Convert reads it locally through a bounded safe text profile with external includes disabled, and converts to HTML, Markdown and plain text. Unsupported extensions and macros are omitted rather than executed, which is the trade the safe profile makes.

Document header attributes such as title and author are read; Markdown and plain text have no attribute channel to receive them.