Asciidoctor PDF converts AsciiDoc to PDF without an intermediate format

The intermediate format is the part Asciidoctor PDF removes

Most pipelines that produce a PDF from a markup source do it in two steps. A converter turns the source into an intermediate representation such as DocBook, Apache FO or LaTeX, and a separate engine renders that intermediate form. Every one of those steps is a place where the layout can drift from what the author wrote, and every one of them is a dependency to install and maintain.

Asciidoctor PDF is the `pdf` backend for Asciidoctor, and it takes the direct route. The project describes it as a native PDF converter that bypasses generating an intermediary format in order to produce a PDF, so you convert your documents directly from AsciiDoc to PDF with Asciidoctor.

That is the whole proposition, and it has an obvious consequence: the tool is Ruby code, in the same process as Asciidoctor itself, rather than a wrapper around an external rendering stack. There is no LaTeX distribution to configure, and no XSLT pipeline to debug. What you get instead is a Ruby library whose behaviour is defined by Ruby gems, which is a real trade in a different direction.

The audience is a team already writing AsciiDoc, usually for technical documentation, that also has to deliver a PDF. The stated aim is to take the pain out of creating PDF documents from AsciiDoc, and the coverage claim is that to the degree possible, Asciidoctor PDF supports all the features of AsciiDoc that Asciidoctor supports, plus a set of PDF specific features.

Prawn does the page layout

The rendering engine underneath is Prawn, a general purpose PDF generator for Ruby. The project documentation describes Prawn as offering high-level APIs for common needs such as setting up the page and inserting images, and low-level APIs for positioning and rendering text and graphics.

The important thing about Prawn for an AsciiDoc author is that the page geometry is not negotiable in the way it is in a word processor. Text has to be positioned, tables have to be laid out, and page breaks have to be decided, and each of those is a place where the document can overflow or break badly. The documentation is upfront that there are certain limitations imposed by the PDF format and by the PDF library the extension uses, and it links to a limitations section alongside the features page.

Asciidoctor PDF also leans on Prawn's extension gems. prawn-svg renders SVG images and prawn-table handles table layout, so a document that contains an SVG diagram or a wide table depends on those gems being present, which they are because they are installed as part of the main gem. The same is true of prawn-icon, which backs the icon font, and ttfunk, which handles font embedding and subsetting.

The result is that a PDF from this converter is laid out by Ruby code with a fixed set of page primitives, not by a word processor. That is precisely why it is fast and reproducible, and precisely why the layout of a complex document takes tuning.

A theme file holds the design decisions

The style and layout of the PDF are controlled by a dedicated theme file, and this is the separation that makes the tool practical for a team. The content stays in the AsciiDoc source, and everything about how it looks, the fonts, the colours, the page size, the header and footer, the spacing, moves into a YAML theme that can be changed without touching a single document.

The examples in the repository show what a theme looks like in practice. There is a `chronicles-theme.yml` alongside `chronicles-dark-theme.yml`, plus a matching `chronicles-example.adoc` and its generated PDF, and a separate `basic-example.adoc` with `basic-example.pdf` that shows the default output. `edge-cases.adoc` sits there for the documents that are awkward to typeset.

Because the design decisions live in that theme file and not in the document, changing the look of the output means changing the theme, not rewriting the source.

For a team with a brand, the theme is the artifact that matters, and it is a YAML file that a designer or a documentation lead can adjust without writing Ruby.

Installing the gem, then checking the two commands that matter

The runtime requirement is a Ruby runtime, and the supported versions are Ruby 2.7 or greater and JRuby 9.2 or greater, with the project recommending the most recent release of either. The check is a single command, and it should report a version starting with 2.7 or 9.2:

ruby -v

The installation is the standard gem install, and it pulls in the dependencies automatically, including asciidoctor, prawn, prawn-svg, prawn-table, prawn-icon and ttfunk:

gem install asciidoctor-pdf

For most of those dependencies the versions are locked to the version of Asciidoctor PDF while patch versions are allowed to vary, which keeps a group of gems in step without freezing them entirely. The minimum supported version of the asciidoctor gem is 2.0.10, and that floor is worth checking against the version already in your project, because an existing Asciidoctor installation that predates it will need a bump.

The first run is a version check of the executable, and it should print the version of Asciidoctor PDF:

asciidoctor-pdf -v

If you want the newest prerelease from RubyGems.org, the flag is `--pre`. A developer who wants to work on the converter itself is pointed at CONTRIBUTING-CODE.adoc for running the code from source, and the repository holds a Rakefile, a `spec/` directory and a `tasks/` directory for that purpose.

Optional gems cover highlighting, hyphenation, optimization and images

Several capabilities are not in the box and need an extra gem, which is worth knowing before you promise a feature in a document template.

Source highlighting needs a syntax highlighter installed, and the documentation marks this as a build-time only requirement, meaning the highlighter is needed on the machine that converts the document, not on the machine that reads the PDF. PDF optimization needs either rghost or hexapdf, and the project links to a dedicated page for the installation and usage instructions.

Automatic hyphenation is enabled with the `hyphens` attribute and requires the `text-hyphen` gem:

gem install text-hyphen

Image handling has a specific limitation, and the project is direct about it. Ruby is not particularly fast at decoding images, and the formats it supports are limited. The remedy is prawn-gmagick, which delegates the decoding work to GraphicsMagick and thereby enables additional image file formats.

That last item is the one that tends to bite in practice. A document with a large number of images will spend time in the decoder, and a document with an image format Ruby cannot read will fail at build time unless GraphicsMagick is present. The documentation also points to a minimum supported version table for these dependencies, which is the file to consult when an optional feature misbehaves.

Version 2 closed out the 1.6 line

The maintenance picture for this converter is a matter of version line discipline. The current releases are in the 2.3.x series, with v2.3.27 published on 2026-09-12, v2.3.26 on 2026-09-02 and v2.3.25 on 2026-08-31. The repository is not archived, and the last push was on 2026-10-15, so patch work continues after those tags.

The older line is explicitly closed. The README carries a note pointing anyone still on Asciidoctor PDF 1.6 at the v1.6.x branch, and states that version 1.6 is no longer being developed and will reach end of life later in the year, with an encouragement to migrate to version 2. For a project that was written against 1.6, that is a migration with a deadline attached, and the version 2 documentation is the reference for it.

The licence is MIT, which means the gem can be used, modified and redistributed inside a commercial product, including inside a closed-source build pipeline, with the obligation to keep the copyright and permission notice. A NOTICE.adoc file sits in the repository root next to the LICENSE.

One documentation gap is worth flagging. The overview states that to the degree possible the converter supports the AsciiDoc features Asciidoctor supports, and that there are limitations imposed by the PDF format and the PDF library. It does not enumerate them there, so the limitations page has to be read before committing to a feature-heavy template.

Where a different toolchain is the better answer

The genuine alternative is to keep the intermediate format and use a different rendering stack, and the difference shows up in what each approach optimises for.

The intermediate route converts AsciiDoc to an intermediate form and renders that with a separate engine, which is the traditional path and the one Asciidoctor PDF deliberately removes. Its advantage is separation: the layout engine is a mature standalone project with its own typography features, page masters and catalogue of layout primitives, and it is the right choice when the PDF needs capabilities the Ruby stack does not attempt. Its cost is a second toolchain, an intermediate artefact to debug when output is wrong, and a longer pipeline.

The native route trades that engine breadth for a single process and a theme file. Layout decisions live in YAML and in Ruby extensions, iteration is fast because there is no intermediate file to inspect, and the output is deterministic for a given source and theme. The limit is that a document demanding unusual page furniture is fighting a fixed set of Prawn primitives.

There is a third axis that decides this for most teams, and it is not technical. A PDF that has to meet an accessibility conformance requirement, or that has to be produced by a team that does not want Ruby in the toolchain at all, is a case for a different pipeline. Asciidoctor PDF is the right answer when Ruby is already present, the AsciiDoc source is the master, and the PDF is one of several outputs.

Editorial conclusion

Asciidoctor PDF fits a documentation team that writes in AsciiDoc, wants a PDF from the same source without installing a TeX distribution, and accepts a Ruby toolchain in its build. It is the wrong choice when the deliverable is an accessible tagged PDF with a strict conformance requirement, or when the team wants a single toolchain for HTML and PDF. Check first the limitations page for the features you rely on, then confirm the Asciidoctor gem version you have, since Asciidoctor PDF 2.3.x requires Asciidoctor 2.0.10 or newer.

Frequently asked questions

Official sources

1. asciidoctor/asciidoctor-pdf on GitHub
2. License: MIT
3. Project website
4. README
5. Releases