Эталон — Asciidoctor 2.0.23. adoctra стремится к тем же документам, той же структуре и тем же диагностикам, чтобы смена обработчика не меняла то, что вы пишете.
Как это проверяется
- Содержимое и структура документов сравниваются с Asciidoctor на закреплённых корпусах — документации Asciidoctor, Spring, Quarkus, Gradle, Hibernate ORM, JUnit и других — и на адаптированном наборе upstream-тестов.
- Диагностики (предупреждения, ошибки и их позиции) сравниваются по сообщениям.
- Поведение командной строки сравнивается по сценариям: коды выхода, выходные файлы, сообщения.
- HTML сравнивается визуально по снимкам экрана, а не побайтно: adoctra пишет современную семантическую разметку.
- Диаграммы сверяются с asciidoctor-diagram 3.2.1, подсветка — с Rouge.
Известные отличия
- HTML использует современную семантическую разметку (
main,section,aside,nav), поэтому таблицы стилей и скрипты, завязанные на точный HTML Asciidoctor, нужно проверить. Встроеннаяadoctra.cssдаёт тот же вид, что и стандартная таблица стилей Asciidoctor. - Нет бэкендов DocBook и man, нет PDF и EPUB. DOCX и JSON — собственные форматы adoctra.
- Расширения, шаблоны (
-T) и библиотеки Ruby (-r, кромеasciidoctor-diagram) не поддерживаются; используйте API расширений на Rust. - Режим безопасности команды по умолчанию —
safe(у Asciidoctor —unsafe). - В браузере диаграммам PlantUML нужен
preprocess=false, а диаграммы рисуются только через сервер.
Полный реестр проверенных областей и открытых расхождений — в docs/compatibility.adoc.
Как сообщить об отличии
Если документ конвертируется не так, как в Asciidoctor, создайте issue с минимальным примером. Сократить пример удобно в песочнице.