The reference is Asciidoctor 2.0.23. adoctra aims at the same documents, the same structure and the same diagnostics, so that switching processors does not change what you write.
How it is checked
- Document content and structure are compared with Asciidoctor on pinned corpora — the documentation of Asciidoctor, Spring, Quarkus, Gradle, Hibernate ORM, JUnit and others — and on the adapted upstream test suite.
- Diagnostics (warnings, errors and their positions) are compared message by message.
- Command-line behavior is compared scenario by scenario: exit codes, output files, messages.
- HTML is compared visually with screenshots, not byte for byte: adoctra writes modern semantic markup.
- Diagrams are checked against asciidoctor-diagram 3.2.1, highlighting against Rouge.
Known differences
- HTML uses modern semantic markup (
main,section,aside,nav), so stylesheets or scripts that depend on Asciidoctor’s exact HTML need checking. The bundledadoctra.cssgives the same look as Asciidoctor’s default stylesheet. - No DocBook or man page backends; no PDF or EPUB. DOCX and JSON are adoctra’s own formats.
- Ruby extensions, templates (
-T) and libraries (-rother thanasciidoctor-diagram) are not supported; use the Rust extension API. - The default safe mode of the command is
safe(Asciidoctor:unsafe). - In the browser, PlantUML diagrams need
preprocess=false, and diagrams are rendered only through a server.
The full register of verified areas and open differences (in Russian) is in docs/compatibility.adoc.
Reporting a difference
If a document converts differently than with Asciidoctor, please open an issue with a minimal example. The playground is a quick way to reduce one.