PDF Extension

The Antora PDF extension is an exporter extension for Assembler that handles converting content prepared by Assembler to the PDF format using Asciidoctor PDF by default. The Antora PDF extension is the official extension for exporting content in an Antora site to PDF.

Summary

package name: @antora/pdf-extension
require name: @antora/pdf-extension
backend: pdf
extname: .pdf
mediaType: application/pdf
default configuration file: ./antora-assembler-pdf.yml
default command: asciidoctor-pdf --sourcemap (prefixed with bundle exec if bundle lockfile is present, honoring BUNDLE_LOCKFILE or BUNDLE_GEMFILE environment variable)

Description

The Antora PDF extension is based on Antora Assembler. It provides the converter metadata and convert function that Assembler uses to export content. The rest is handled by Assembler itself.

Assembler constructs the content of assembly files from pages per component version using the navigation as a model. Using the converter provided by this extension, it then iterates over those assembly files and converts them to PDF using Asciidoctor PDF (or the specified command). Finally, it adds those PDFs to the content catalog as exports, which Antora then publishes alongside the other files in the site.

Configuration

Set Asciidoctor PDF options

Asciidoctor PDF has limited CLI options for setting processor options (as of the latest stable release). For example, you can’t yet control the log level. (For other Asciidoctor converters, you can’t control the sourcemap either).

You can configure the Asciidoctor PDF command (asciidoctor-pdf) require an Asciidoctor preprocessor extension to set these options from inside the Asciidoctor runtime. You can also use it to set compliance settings to optimize AsciiDoc parsing.

Example 1. lib/configure-asciidoctor-pdf.rb

Asciidoctor::Compliance.markdown_syntax = false (1)
Asciidoctor::Compliance.underline_style_section_titles = false (2)

Asciidoctor::Extensions.register do
  preprocessor do
    process do |doc|
      doc.logger.level = :INFO (3)
      nil
    end
  end
end

1	Turn off Markdown syntax since it’s not used in Antora or Assembler
2	Turn off setext section titles, which is legacy AsciiDoc syntax and can interfer with line number tracking
3	Set the log level to INFO to catch possible invalid references

To register the extension, add it to the command in the Assembler config as follows:

build:
  command: asciidoctor-pdf -r ./lib/configure-asciidoctor-pdf.rb

This extension also gives you the opportunity to register an extended converter. To learn how to make an extended PDF converter, see ^Extend the Asciidoctor PDF converter.

You can also register an optimizer to optimize the PDFs using the same extension file. See Compress a PDF using HexaPDF to find the necessary code.