Register the Extension

Once an exporter extension is installed, you need to register that extension with Antora. The extension can be registered in your Antora playbook or through the CLI.

Register in the playbook

To register the extension in your Antora playbook, add an entry to the playbook file under the antora.extensions key that specifies the name of the extension package.

Open your Antora playbook file (antora-playbook.yml) and add the extension as follows:

Example 1. antora-playbook.yml

antora:
  extensions:
  - '@antora/pdf-extension'
# ...

The quotes are required around the package name because @ is a special character in YAML.

You will also want to set the site.url key in the playbook (or from the CLI) when using Assembler.

Example 2. antora-playbook.yml

site:
  url: https://docs.example.org

The site URL is used to create links to references that reach outside the boundaries of the assembly (and thus the export). Since the export can be downloaded independent of the site, the only way to guarantee these references work is to link to the resource in the published site. If the site URL is not set, the target of these references will remain unresolved (without a warning).

You can now run Antora to have Assembler generate and publish the export files.

$ antora antora-playbook.yml

Instead of modifying the playbook, you can register the PDF extension when running Antora.

Register from the CLI

Alternately, you can register the PDF extension at your discretion using the --extension CLI option of the antora command:

$ antora --extension @antora/pdf-extension antora-playbook.yml

It’s possible to configure the extension when activating it through the CLI by adding an entry for it in antora.extensions in the playbook with the enabled key set to false. See Enable an Extension to learn more about how this works.

Extension configuration

The extension entry in the playbook provides a place to configure how the extension is registered. These configuration keys are described in the section below.

The playbook must be used to set global configuration defaults even when the extension is registered from the CLI.

config_file key

By default, Assembler will look for a configuration file named antora-assembler.yml next to the playbook file. You can change the location and name of this file using the config_file key.

Example 3. antora-playbook.yml

antora:
  extensions:
  - register: '@antora/pdf-extension'
    config_file: ./assembler-pdf.yml
# ...

Aside from an organizational choice, this key allows you to use the same exporter extension multiple times, each with its own configuration.

Example 4. antora-playbook.yml

antora:
  extensions:
  - register: '@antora/pdf-extension'
    config_file: ./assembler-pdf-group-a.yml
  - register: '@antora/pdf-extension'
    config_file: ./assembler-pdf-group-b.yml
# ...

This topic will be covered in more depth in Configure Assembler.

Now that you have registered the extension, you can configure Assembler in the antora-assembler.yml file in the playbook project for your site.