asciidoctor: Convert AsciiDoc to HTML
asciidoctor converts .adoc files to standalone HTML5 by default, with attributes and a configurable failure level.
Asciidoctor is the AsciiDoc processor used by many docs sites and books. In CI, --failure-level is the switch that makes a broken include or missing image fail the build.
What it does
asciidoctor parses AsciiDoc, resolves includes and attributes, and renders an output (HTML5 by default). -o sets the output file, -D the output directory, and -a overrides document attributes. Diagnostics are graded INFO/WARN/ERROR and gated by --failure-level.
Common usage
asciidoctor index.adoc
asciidoctor -D public -o index.html docs/index.adoc
# fail the build on any warning or worse
asciidoctor --failure-level=WARN -a toc=left index.adocOptions
| Flag | What it does |
|---|---|
| -o <file> | Output file name |
| -D <dir> | Output directory |
| -b <backend> | Backend: html5 (default), docbook5, manpage |
| -a <name=value> | Set or override a document attribute |
| --failure-level <lvl> | Exit non-zero at WARN or ERROR |
| -r <library> | Require a Ruby extension library |
| -S <mode> | Safe mode: unsafe, safe, server, secure |
In CI
Pass --failure-level=WARN so a missing include or unresolved reference fails the pipeline instead of silently emitting a warning. If you use extensions like asciidoctor-diagram, -r them and install the required tools (for example Graphviz) on the runner.
Common errors in CI
asciidoctor: WARNING: include file not found: partials/intro.adoc fails the build under --failure-level=WARN. asciidoctor: ERROR: section title out of sequence: expected level 1, got level 2 flags a heading level jump. LoadError: cannot load such file -- asciidoctor-diagram means the extension gem is not installed.