Configuration Tutorial

As explained in How are pages merged?, Assembler uses the site navigation to determine which pages to merge to create an assembly. Unless you want to use alternate navigation for the assembly, there’s nothing you need to do differently from what you’ve already done to define the navigation for your site. However, it’s worth illustrating how the navigation is used.

Let’s assume we’ve defined the navigation for a compoment version in our site as follows:

Assuming the root level is 0 (one export per component version), Assembler will create an assembly with the following section hierarchy:

How the sections in each page are merged depends on the section merge strategy setting. But that’s enough for us to get started.

In this section, we’ll step through creating the optional 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 adding the names key under the component_version_filter category key and assigning glob pattern values to it. By default, the value is * (latest version of every component). Let’s configure it to create PDFs for every component version instead by setting the value to **.

In your new antora-assembler.yml file, enter the key name component_version_filter directly followed by a colon (:) and a space. On a new indented line, enter the key name names 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.

See Configure the Component Version Filter for more pattern examples.

Next, set the attributes key under the assembly key so you can assign some AsciiDoc attributes to PDFs. On a new line, enter the key name assembly, followed by a colon (:). On a new indented line, enter the key name attributes followed by a colon (:). On a new indented line, 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.

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.

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.

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 indented line, enter the name of the attribute pdf-theme followed by a colon (:), a space, and the value ./pdf-theme.yml.

(Alternately, you can specify the PDF theme using the --theme CLI option of the Asciidoctor PDF command).

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

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).

Then run the bundle command:

You also need to require Asciidoctor Kroki 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 (:). Under the build key, nest the command key and assign it the value bundle exec asciidoctor-pdf -r asciidoctor-kroki.

Notice we’ve set the allow-uri-read attribute. This setting is required to generate PDFs with Asciidoctor PDF and EPUB if Kroki is not configured to fetch diagrams. That’s because the converter has to handle fetching the diagram.

Alternately, you can configure Asciidoctor Kroki to fetch the diagrams itself.

Diagrams will be written to the same directory as the export file in the build directory. The converter will read the generated diagrams from there.

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

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

If you’re using Asciidoctor Diagram instead of Asciidoctor Kroki to generate diagrams, you’ll want to configure the cache location. This way, the cache is preserved across runs. We can leverage the $PWD environment variable reference to put it next to our playbook. (You can also do the same to configure the path to diagram binaries and/or bin scripts).

Diagrams will be written to the same directory as the export file in the build directory. The converter will read the generated diagrams from there.

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.

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:

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.

Now you’re ready to run Antora to generate and publish your 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.

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).