asciidoctor-pdf: AsciiDoc to PDF in CI
asciidoctor-pdf converts AsciiDoc straight to PDF using Prawn, so no LaTeX or wkhtmltopdf is required.
When you need a PDF from AsciiDoc, asciidoctor-pdf is the direct path: pure Ruby, no LaTeX. Theming and embedded fonts are the two things that trip up CI.
What it does
asciidoctor-pdf is the PDF backend for Asciidoctor. It reads AsciiDoc and produces a PDF via the Prawn library, applying a YAML theme (pdf-theme) and looking up fonts in pdf-fontsdir. It shares Asciidoctor CLI flags like -o and --failure-level.
Common usage
asciidoctor-pdf book.adoc
asciidoctor-pdf -o out/book.pdf book.adoc
# apply a custom theme and font directory
asciidoctor-pdf -a pdf-theme=theme.yml -a pdf-fontsdir=fonts book.adocOptions
| Flag / attribute | What it does |
|---|---|
| -o <file> | Output PDF path |
| -a pdf-theme=<file> | YAML theme controlling layout and fonts |
| -a pdf-fontsdir=<dir> | Directory to resolve theme fonts from |
| --failure-level <lvl> | Fail at WARN or ERROR |
| -a media=prepress | Render for print (crop marks, CMYK-ish) |
In CI
Commit the fonts your theme references and point pdf-fontsdir at them, so builds do not depend on system fonts that differ between runners. Use --failure-level=WARN to catch missing images. The gem is asciidoctor-pdf; install it alongside asciidoctor.
Common errors in CI
Failed to load font family 'Noto Serif' ... could not be found means the font is not in pdf-fontsdir; ship the .ttf files. image to embed not found or not readable flags a missing image path. undefined method ... for Asciidoctor::Pdf usually means an asciidoctor-pdf version incompatible with the installed asciidoctor.