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

Assembly profiles are only available when using Antora 3.2.0 or better. Previous versions of Antora do not support the required generator event (componentsRegistered) that is necessary to support this feature.

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 effectively becomes a single profile, 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.

Additional attributes

An assembly profile provides an opportunity to specify additional attributes that are scoped to the component version. Like all keys on the profile, the attributes key is optional. These attributes provide an opportunity to conditionally include content for a given export format and to override settings on the exporter’s converter, such as the PDF theme, section numbering, hiding the URI scheme, and so forth.

If an attribute has already been defined elsewhere, the attribute defined in the profile takes precedence (either to set or unset the previously defined attribute). Using attribute references to inherited attributes (e.g., site-wide attributes) is also permissible.

An attribute defined on an assembly profile with same name as attribute defined on the assembly in the Assembler configuration (i.e., base assembly) replaces that entry. In other words, it effectively updates the value of the attribute. It does not resolve the attribute value before the update.

These additional attributes must be declared on the attributes key. The entries work just like attributes defined in the playbook, component version descriptor, or Assembler configuration file.

Example 2. antora.yml

name: the-component
version: '1.0'
nav:
- modules/ROOT/nav.adoc
ext:
  assembler:
  - profile: pdf
    attributes:
      pdf-theme: alternate-pdf-theme.yml
      sectnums: ''

The additional attributes can be defined on any Assembly profile. Only the attributes associated with the selected profile are used.

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. For example, the assembler-loader attribute is only set when reading a nav file in an assembly profile, not when reading the nav file for the site. If the attribute is set, you can include entries for the PDF. If the attribute is not set, you can include entries for the site.

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

Example 3. 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 4. 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