Install an Extension

Antora Assembler is typically installed by installing an exporter extension. The flagship exporter extension is the PDF extension.

Assembler and its built-in exporter extensions require Node.js 22.15.0 or greater and Antora 3.2.0-alpha.8 or greater. No external commands are required by Assembler itself. However, the exporter extension may require the use of an external converter command to convert the assembly files to the target format. These commands are specified using the build.command key in the Assembler configuration.

Prerequisites

Assembler and the Antora PDF Extension require the following software, listed by minimum version supported: Ruby 2.7, Asciidoctor PDF 2.3, Node.js 22.15.0, and Antora 3.2.0-alpha.8.

The instructions in the following sections assume you’ve already set up a playbook project, an Antora playbook file (i.e., antora-playbook.yml), and that you’re running the commands from your playbook project.

Node.js

This software requires Node.js 22.15.0 or greater. To see if you have Node.js installed, and which version, type:

$ node -v

You should see a version string, such as:

$ node -v
v22.15.0

If no version number is displayed in your terminal, you need to install Node.js. Follow one of these guides to learn how to install nvm and Node.js on your platform.

Antora

Assembler requires Antora 3.2.0-alpha.8 or greater. To confirm you have a suitable version of Antora installed, run:

$ npx antora -v

The command should report the version of the Antora CLI and site generator you have installed. If you’re not yet using Antora 3.2.0-alpha.8 or greater, you need to upgrade to use Assembler.

Antora playbook project

We highly recommend that you install this software and its prerequisites in your playbook project, the directory where your site’s Antora playbook file (e.g., antora-playbook.yml) is located. If you install the prerequisites and PDF extension globally, conflicts with other installed software and versions may occur.

When you’re evaluating Assembler for the first time, we recommend starting with the Antora demo.

$ git clone https://gitlab.com/antora/demo/docs-site.git assembler-tutorial && cd assembler-tutorial

By starting out this way, you can learn how Assembler works without having to worry about other complexities. We know that Assembler works with the Antora Demo. Once you get that working, you can move on to using it on your own Antora playbook project while still being able to refer back to the demo.

Ruby

The Antora PDF extension uses Asciidoctor PDF by default to export assembly files. Asciidoctor PDF requires either Ruby 2.7 or greater (or JRuby 9.2 or greater).

We strongly encourage you to use the latest stable Ruby version. To check if you have Ruby available, run the ruby command to print the installed version:

$ ruby -v

You should see a version string, such as:

$ ruby -v
ruby 3.3.0 (2023-12-25 revision 5124f9ac75) [x86_64-linux]

Make sure this command reports a Ruby version that starts with 2.7 or greater (or a JRuby version that starts with 9.2 or greater). If it doesn’t, go to rvm.io to set up RVM and use it to install a version of Ruby.

Asciidoctor PDF

The Antora PDF Extension uses Asciidoctor PDF to generate PDF files from AsciiDoc. We recommend installing Asciidoctor PDF into your project using a Gemfile managed by Bundler.

Start by creating a file named Gemfile and adding an entry for asciidoctor-pdf as follows:

Example 1. Gemfile
source 'https://rubygems.org'

gem 'asciidoctor-pdf'

Next, configure Bundler to install gems inside the project:

$ bundle config --local path .bundle/gems

Then run Bundler as follows:

$ bundle

If you want to apply syntax highlighting to source blocks in your PDF files, you’ll also need a syntax highlighter that’s supported by Asciidoctor PDF. Let’s install Rouge by adding an entry for the rouge gem in the Gemfile.

Example 2. Gemfile
source 'https://rubygems.org'

gem 'asciidoctor-pdf'
gem 'rouge'

Run the bundle command again.

If you prefer to install Asciidoctor PDF globally, you can use the gem install command instead. Pass the name of the gem, asciidoctor-pdf, to the gem install command as follows:

$ gem install asciidoctor-pdf

If you have problems installing Asciidoctor PDF, see the installation troubleshooting tips.

As an alternative to setting up Ruby and installing the Asciidoctor PDF gem, you can use AsciidoctorJ. First, install the AsciidoctorJ distribution using sdkman.

$ sdk install asciidoctorj

Later, when configuring the build command, you’ll use asciidoctorj -b pdf (instead of the default command, bundle exec asciidoctor-pdf).

Once you’ve satisfied the prerequisites, you’re ready to install an Assembler exporter extension in your playbook project.

Install the extension package

To install the package for the PDF extension in your playbook project, type the following command:

$ npm i @antora/pdf-extension

Other exporter extensions are similarly named (e.g., @antora/epub-extension).

This command installs the extension package as well as Assembler. The packages are installed alongside Antora and any other extensions or libraries you’re using in your playbook project.

We strongly recommend that you install Antora, this extension, and any other extensions that you use in your playbook project, the directory the Antora playbook file (e.g., antora-playbook.yml) for your site is located. If you install the npm packages globally, they can interfere with other software install on your system and conflicts may occur.

Alternately, you can install the extension on demand (without having to first install it in the playbook project) using npx.

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

Now that the extension is installed, you need to register the extension in your playbook or require it at runtime (even if you install the extension on demand using npx).