adoctra повторяет команду asciidoctor: результат записывается рядом с исходным файлом под тем же именем.

Примеры

adoctra document.adoc                     # document.html
adoctra -o - document.adoc                # HTML в stdout
adoctra -e document.adoc                  # фрагмент HTML (без шапки и подвала)
adoctra --to docx document.adoc           # document.docx
adoctra --to json document.adoc           # document.json
adoctra -D build/ docs/*.adoc             # несколько файлов в каталог
adoctra -a toc -a icons=font -n book.adoc # атрибуты, нумерация разделов
adoctra -a source-highlighter=rouge document.adoc

Несколько входных файлов конвертируются по порядку. Имя, не являющееся файлом, раскрывается как glob (, ?, […], {a,b}, */), а - читает стандартный ввод.

Опции

Опция Назначение

-b, --backend

html5 (по умолчанию), xhtml5, docx, json

--to FORMAT

html, docx или json

-d, --doctype

article (по умолчанию), book, manpage или inline

-a NAME[=VALUE]

задать атрибут документа (name@ или value@: документ может его переопределить; name! снимает атрибут)

-o FILE

выходной файл (- — stdout)

-D DIR

выходной каталог

-R DIR

корень исходников: подкаталог входного файла ниже него сохраняется в -D

-B DIR

базовый каталог документа и его ресурсов

-S MODE

режим безопасности: unsafe, safe (по умолчанию), server или secure

-e, -s

фрагмент документа, без шапки и подвала

-n

нумеровать разделы

--failure-level LEVEL

код выхода 1 при сообщениях этого уровня (WARN, ERROR, …)

-q, -v

без сообщений или с информационными

-t

вывести время этапов

-r asciidoctor-diagram

включить диаграммы

-h, -V

справка, версия

Собственные опции adoctra:

Опция Назначение

--to html|json|docx

формат вывода по имени

--stdout

записать результат в стандартный вывод

--json-attributes

включить атрибуты документа в JSON

--json-locations

добавить "location": {"file", "line"} каждому блоку, пункту списка и ячейке таблицы

--json-references

включить каталог зарегистрированных id

--diagnostics compat|editor

формат сообщений

Опции разбираются как в OptionParser Ruby: уникальные префиксы длинных опций (--em), формы --name=value и --name value, склеенные короткие флаги (-sn) и присоединённые значения (-Ssafe, -o-). -- завершает опции.

Режим безопасности

Сообщения и код выхода

Сообщения выводятся в stderr в виде adoctra: file:LINE: warning: …. Каждое сообщение повышает максимальную серьёзность; с --failure-level WARN команда завершится с кодом 1, если было хотя бы одно предупреждение, — это удобно в CI:

adoctra --failure-level WARN -D public docs/*.adoc

-o /dev/null только загружает документ: диагностики выводятся, но ничего не конвертируется и не записывается.

Что не поддерживается

Шаблоны Ruby (-T, -E), библиотеки Ruby (-r, кроме asciidoctor-diagram), бэкенды DocBook и man. Расширения пишутся на Rust через API расширений.