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

Component version overrides

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. The map accepts all the keys supported by the assembly key as well as the profile and nav keys.

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