Configure Assembler

Assembler allows you to specify an optional configuration file that controls both the assembly process itself and the exporter. This page introduces this configuration file and how it’s detected by Assembler. Subsequent pages provide detail about each section and key in the configuration file.

antora-assembler.yml

The Assembler configuration file provides a way to specify configuration that only applies to the assembly and exporter, s separate from the Antora configuration, such as additional AsciiDoc attributes.

The name and location of the Assembler configuration file is detected automatically unless an alternate file is specified when registering the extension. By default, the file is named antora-assembler-<backend>.yml (e.g, antora-assembler-pdf.yml) or antora-assembler.yml adjacent to your Antora playbook file in the playbook project.

📒 repository
  📄 antora-assembler.yml
  📄 antora-playbook.yml

You should only name the configuration file antora-assembler.yml if you’re using Assembler to export to exactly one format (i.e., backend), or the configuration can be generalized for all formats. If you’re using Assembler to export to multiple formats, you should use a configuration file per format. For example, when exporting to both PDF and EPUB, you would name the configuration files antora-assembler-pdf.yml and antora-assembler-epub.yml, respectively.

📒 repository
  📄 antora-assembler-epub.yml
  📄 antora-assembler-pdf.yml
  📄 antora-playbook.yml

You can specify an alternate configuration file using the config_file key (or multiple using the config_files key) when registering the extension.

Assembler logs a warning if you specify a configuration file and that file does not exist. Assembler does not throw an error if it doesn’t find a configuration file at the path specified or the default path when no configuration file is specified. Either way, Assembler will proceed with the default settings.

enabled key

Even if an exporter extension is registered with the Antora runtime, you can quickly deactivate (that instance of) Assembler in the Assembler configuration by setting the top-level enabled key to false. This key accepts a Boolean value. By default, the implicit value of this key is true.

Example 1. antora-assembler.yml
enabled: false

This key offers a quick and convenient way to deactivate Assembler without having to modify the Antora playbook or the CLI options.

Going further

You can switch to programmatic configuration of Assembler if you want even more control over how Assembler works and what navigation it uses.