adoctra follows the asciidoctor command: the output is written next to the input and named after it.

Examples

adoctra document.adoc                     # document.html
adoctra -o - document.adoc                # HTML to stdout
adoctra -e document.adoc                  # embedded HTML (no header/footer)
adoctra --to docx document.adoc           # document.docx
adoctra --to json document.adoc           # document.json
adoctra -D build/ docs/*.adoc             # several files into a directory
adoctra -a toc -a icons=font -n book.adoc # attributes, section numbers
adoctra -a source-highlighter=rouge document.adoc

Several inputs are converted in order. A name that is not a file is expanded as a glob (, ?, […], {a,b}, */), and - reads standard input.

Options

Option Meaning

-b, --backend

html5 (default), xhtml5, docx, json

--to FORMAT

html, docx or json

-d, --doctype

article (default), book, manpage or inline

-a NAME[=VALUE]

set a document attribute (name@ or value@: the document may override it; name! unsets it)

-o FILE

output file (- for stdout)

-D DIR

output directory

-R DIR

source root: keep the input’s subdirectory below it in -D

-B DIR

base directory of the document and its resources

-S MODE

safe mode: unsafe, safe (default), server or secure

-e, -s

embedded document, without header and footer

-n

number sections

--failure-level LEVEL

exit with status 1 on messages of this level (WARN, ERROR, …)

-q, -v

no messages, or also informational ones

-t

print timings

-r asciidoctor-diagram

enable diagrams

-h, -V

help, version

Options adoctra adds:

Option Meaning

--to html|json|docx

output format by name

--stdout

write the result to standard output

--json-attributes

include document attributes in JSON output

--json-locations

add "location": {"file", "line"} to every block, list item and table cell

--json-references

include the catalog of registered ids

--diagnostics compat|editor

message format

Options are parsed like Ruby’s OptionParser: unique prefixes of long options (--em), --name=value and --name value, grouped short flags (-sn) and attached values (-Ssafe, -o-). -- ends the options.

Safe mode

Messages and exit status

Messages go to standard error as adoctra: file:LINE: warning: …. Every message raises the maximum severity; with --failure-level WARN the command exits with status 1 if any warning was reported, which is handy in CI:

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

-o /dev/null only loads the document: diagnostics are reported, nothing is converted or written.

Not supported

Ruby templates (-T, -E), Ruby libraries (-r other than asciidoctor-diagram) and the DocBook and man page backends. Extensions are written in Rust through the extension API.