Configuration Tutorial

This page walks you through configuring the Antora PDF extension so you can generate PDFs from the content in your site and be ready to start customizing those PDFs to your liking.

We’ll assume in this tutorial that the exports we’re creating are PDFs since we’re using the Antora PDF extension—the official PDF exporter extension. If you’re using a different exporter extension, the target format may be different.

Before you get started, head on over to Install an Extension to make sure you have all the necessary prerequisites and have installed the extension itself.

Create antora-assembler.yml

In this section, we’ll step through creating an antora-assembler.yml file and assigning values to a few common PDF extension keys and AsciiDoc attributes.

Open a new file in the text editor or IDE of your choice. Save the file as antora-assembler.yml in your playbook project.

By default, the extension only generates a PDF for the latest version of each component in your site. You can change this behavior by setting the component_versions key and assigning it picomatch pattern values. Let’s configure it to create PDFs for every component version instead.

In your new antora-assembler.yml file, enter the key name component_versions directly followed by a colon (:) and a space. After the space, enter two asterisks (**) and enclose them in a set of single quotes. The value ** tells the extension to generate PDFs for every component version in your site.

Example 1. antora-assembler.yml

component_versions: '**'

See Configure the Component Version Filter for more pattern examples.

Next, set the asciidoc and attributes keys so you can assign some AsciiDoc attributes to PDFs. On a new line, enter the key name asciidoc, followed by a colon (:), and then press Enter to go to the next line. Nest the attributes key under the asciidoc key. On a new line nested under the attributes key, enter the name of the attribute source-highlighter followed by a colon (:), a space, and the value rouge. This attribute turns on source highlighting in the PDF.

Example 2. antora-assembler.yml

component_versions: '**'
asciidoc:
  attributes:
    source-highlighter: rouge

The AsciiDoc attributes specified in antora-assembler.yml are applied to all the generated PDFs according to the attribute precedence rules. To learn more about assigning AsciiDoc attributes in the configuration file, see Configure AsciiDoc.

Create pdf-theme.yml

Let’s set up an Asciidoctor PDF theme for customizing the PDFs the extension generates.

Start by creating a theme file in your playbook directory named pdf-theme.yml. To keep it simple, this theme extends the default theme and sets the font color on a role named red. This gives you something to build on later.

Example 3. pdf-theme.yml

extends: default
role:
  red:
    font-color: #FF0000

In your antora-assembler.yml file, activate the PDF theme by setting the built-in pdf-theme attribute. The pdf-theme attribute accepts the name of a YAML file stored in your playbook directory. In this example, the file is named pdf-theme.yml next to the Assembler configuration file. On a new line nested under the attributes key, enter the name of the attribute pdf-theme followed by a colon (:), a space, and the value ./pdf-theme.yml.

Example 4. antora-assembler.yml

component_versions: '**'
asciidoc:
  attributes:
    source-highlighter: rouge
    pdf-theme: ./pdf-theme.yml

You can customize your PDF theme using Asciidoctor PDF’s theming language.

Configure the command

By default, the PDF extension uses the command bundle exec asciidoctor-pdf if Gemfile.lock is present, otherwise asciidoctor-pdf. However, you may want to pass additional options to the command. For example, let’s say that you have diagrams in your pages that need to be converted. To enable diagram processing, you first need to add the asciidoctor-kroki gem to Gemfile. (If you’re not using diagrams, you can skip this step).

Example 5. Gemfile

source 'https://rubygems.org'

gem 'asciidoctor-pdf'
gem 'asciidoctor-kroki'

Then run the bundle command:

$ bundle

You also need to require Asciidoctor Diagram by passing -r asciidoctor-kroki when calling the asciidoctor-pdf command. In order to do that, we need to customize the command that Assembler runs.

On a new line, enter the key name build, followed by a colon (:), and then press Enter to go to the next line. Under the build key, nest the command key and assign it the value bundle exec asciidoctor-pdf -r asciidoctor-kroki.

Example 6. antora-assembler.yml

component_versions: '**'
asciidoc:
  attributes:
    allow-uri-read: ''
    kroki-fetch-diagram: ~
    source-highlighter: rouge
    pdf-theme: ./pdf-theme.yml
build:
  command: bundle exec asciidoctor-pdf -r asciidoctor-kroki

Notice we’ve set the allow-uri-read attribute and unset the kroki-fetch-diagram attribute. These settings are required when using Kroki with Antora Assembler.

You can use the command key to enable other CLI options, such as --trace and --sourcemap. Both of those options are recommended, so lets add them.

Example 7. antora-assembler.yml

component_versions: '**'
asciidoc:
  attributes:
    allow-uri-read: ''
    kroki-fetch-diagram: ~
    source-highlighter: rouge
    pdf-theme: ./pdf-theme.yml
build:
  command: bundle exec asciidoctor-pdf -r asciidoctor-kroki --sourcemap --trace

To learn more about command and other build settings, such as dir and keep_source, see Configure the Build.

You’ve set up your PDF configuration file! The PDF extension will use this configuration file to generate a PDF for each component version in your site using the content sources specified in your Antora playbook file.

Add a link to the PDF

Although Assembler publishes the export files, in this case the PDFs, by default, there is no link to them. Let’s use Antora’s supplemental UI to add a link to the PDF from a page if that page is included in the PDF. We’ll be adding this link to the toolbar by replacing the UI template partial for the "Edit this Page" link.

Start by creating the file supplemental-ui/partials/edit-this-page.hbs in the playbook project. Populate it with the following template code:

{{#with (resolvePage page.relativeSrcPath model=false)}}
{{#with ./assembler.pdf}}
<p><a href="{{{relativize ./file.pub.url}}}{{{./fragment}}}">PDF</a></p>
{{/with}}
{{/with}}
{{#if (and page.fileUri (not env.CI))}}
<div class="edit-this-page"><a href="{{page.fileUri}}">Edit this Page</a></div>
{{else if (and page.editUrl (or env.FORCE_SHOW_EDIT_PAGE_LINK (not page.origin.private)))}}
<div class="edit-this-page"><a href="{{page.editUrl}}">Edit this Page</a></div>
{{/if}}

The logic for the Edit this Page link has been copied from the original file.

Next, configure Antora to use the supplemental UI files by setting the ui.supplemental_files key to point to the supplemental-ui directory.

Example 8. antora-playbook.yml

# ...
ui:
  # ...
  supplemental_files: ./supplemental-ui

Now you’re ready to run Antora to generate and publish your PDFs.

Run Antora to generate PDFs

All that’s left is to run Antora to generate and publish the PDFs alongside the other files in the site. The quickest way to do so is to use npx to install Antora and the Antora PDF extension and to require/register the PDF extension using the -r option flag of the Antora CLI.

$ npx -y --package antora@testing --package @antora/pdf-extension \
  antora -r @antora/pdf-extension antora-playbook.yml

On each page that is included in a PDF you should find a link to that PDF in the toolbar. Better yet, the link will navigate you to the section of the PDF where that page starts (i.e., deep link).