Configure Assembler

When you configure Assembler, you’re configuring both the assembly process itself and the exporter. Assembler configuration is defined in a file named antora-assembler.yml next to the Antora playbook file by default. An alternate file may be specified when registering the extension.

antora-assembler.yml

The Assembler configuration file is a YAML file that defines settings and AsciiDoc attributes that are only applied to exports. By default, the file must be named antora-assembler.yml and stored in your playbook project adjacent to your Antora playbook.

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

You can specify an alternate configuration file using the config_file key when registering the extension. If Assembler doesn’t find a configuration file at the path specified, or the default path if the config_file key is not set, it will use the default configuration (no error is thrown if the file is missing).

Profiles

By default, the configuration defined in the Assembler configuration file is shared by all component versions in the site. The configuration related to assembly (i.e., the assembly model) may be tailored per component version in its component version descriptor. This includes being able to define alternate navigation for Assembler to use.

The per-component version configuration is defined using the assembler subkey under the ext key in that file. This key accepts either a map, which serves as a single profile entry, or an array of profile entries. When declaring a single profile, or the default profile, the profile key is not required.

Example 1. antora.yml
name: the-component
version: '1.0'
nav:
- modules/ROOT/nav.adoc
ext:
  assembler:
  - profile: pdf
    nav: modules/ROOT/pdf-nav.adoc
    section_merge_strategy: fuse
The ext key is the designated area in the component version descriptor for extensions to define additional configuration.

You can learn how an assembly profile is selected on the Configure the Assembly page.

Alternate navigation

By default, Assembler uses the navigation defined by the nav key in the component version descriptor to assemble content. (Technically, it uses the navigation data assigned to the navigation property on the component version object). When you export content, you may want to organize pages differently, only export a subset of pages, or use preprocessor conditionals to select pages. That’s where the alternate navigation comes in.

Using the nav key in an assembly profile, you can define a different navigation for Assembler to use instead of the main navigation used for the pages in the site. The nav key works the same as the main nav key at the top-level of the component version descriptor. The alternate navigation is scoped to a single component version.

The main navigation has already been built by the time Assembler runs. That means that any preprocessor conditionals in nav files have already been evaluated and are not evaluated again. The alternate navigation provides a way to have nav files evaluated while Assembler is running.

The simplest way to specify alternate navigation is to declare the nav key inside the ext.assembly key in the component version descriptor. If no other profiles are defined, this profile will be used by default.

Example 2. antora.yml
name: the-component
version: '1.0'
nav:
- modules/ROOT/nav.adoc
ext:
  assembler:
    nav:
    - modules/ROOT/assembler-nav.adoc
You can reuse the original nav file and rely on preprocessor conditionals to filter entries instead of defining a dedicated nav file.

If you want to define alternate navigation for each export format, you can do so using named profiles.

Example 3. antora.yml
name: the-component
version: '1.0'
nav:
- modules/ROOT/nav.adoc
ext:
  assembler:
  - profile: pdf
    nav:
    - modules/ROOT/pdf-nav.adoc
  - profile: epub
    nav:
    - modules/ROOT/epub-nav.adoc

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