Configure the Assembly
The core of Assembler’s configuration relates to how pages are assembled, called the assembly model. The assembly model consists of the navigation model that drives the assembly, the level in the navigation at which each assembly starts, and how sections are merged into the hierarchy provided by the navigation.
You can configure how the assembly is modeled using the assembly category key in the Assembler configuration.
assembly key (category)
The assembly category key is an optional key that can be set in the Assembler configuration file (e.g., antora-assembler.yml).
This category defines the assembly model.
Acceptable keys and their default values are listed in the table below.
| Key | Default | Type | Description |
|---|---|---|---|
0 |
0 or 1 |
The level in the navigation from which each assembly should start. 0 means a single assembly. 1 means an assembly per top-level entry in the navigation. |
|
true |
Boolean |
Implicitly inserts the start page at the top of the navigation model when set to |
|
discrete |
discrete, fuse, or enclose |
Controls how Assembler merges page sections with the hierarchy defined by the navigation. |
|
<set by exporter> |
String |
The name of the profile from which to look for alternate navigation and assembly configuration overrides in the component version descriptor. |
root_level
The root_level key controls the depth in the navigation at which the assembly starts.
The root_level key is an optional key that can be set in antora-assembler.yml.
It accepts a value of 0 or 1.
0-
Default. The value
0produces one assembly per matched component version. 1-
The value
1produces an assembly starting from each top-level entry in the navigation tree of each matched component version. In this case, top-level refers to each navigation list. However, if there’s only a single navigation list with no title (or a title that matches the component title), an assembly will be created for each first-level item in that list.
assembly:
root_level: 1If root_level isn’t set, the extension will automatically assign the value 0 at runtime and thus generate an assembly per matched component version.
insert_start_page
The insert_start_page key controls whether the component version start page is implicitly inserted at the top of the navigation model.
The insert_start_page key in an optional key that can be set in antora-assembler.yml.
It accepts a Boolean value.
true-
Default. A true value instructs Assembler to insert the start page at the top of the navigation if it’s not already present.
false-
A false value turns off the described behavior.
assembly:
insert_start_page: falseThis key is necessary since the start page isn’t typically declared in the navigation as the UI template already links to it. By instructing Assembler to insert it implicitly, you ensure that the content from the start page also gets exported. However, if the start page does not contain content that is relevant for an export, you may choose to deactivate this feature.
When the root_level has the value 1, the insert_start_page key effectively adds an export for the start page itself.
In this case, the title of the export will match the component version title.
section_merge_strategy
The section_merge_strategy key controls how the extension merges the sections from pages with sections created to represent navigation entries.
The section_merge_strategy key is an optional key that can be set in antora-assembler.yml.
It accepts the following built-in values:
- discrete
-
Default. The
discretevalue converts all section titles (level 1 (==) and greater) to discrete headings. Discrete headings don’t appear in a TOC or PDF outline. Only the titles of pages referenced in the navigation files are displayed in the PDF outline. - enclose
-
The
enclosevalue inserts a new section title before the preamble of top-level navigation entries and inserts a child navigation entry for the new section under the top-level page. The title of this new nav entry is controlled by the overview-title AsciiDoc attribute, which defaults to “Overview”. The new navigation entry, which encloses the top-level section titles from the page, is inserted before the existing children of the navigation entry, effectively becoming a sibling. - fuse
-
The
fusevalue inserts sections from the page as children of the navigation entry for the current page (shifting levels as necessary). The top-level section titles in the page are inserted before the existing children of the navigation entry, effectively becoming siblings.
The following sections go into more detail about the meaning of each value.
discrete
If section_merge_strategy isn’t set, the extension assigns the value discrete at runtime.
You can also assign it directly to the section_merge_strategy in antora-assembler.yml.
assembly:
section_merge_strategy: discreteLet’s examine how the pages of the colorado 5.2 component version are assembled when section_merge_strategy is discrete.
As shown in Example 4, two navigation files are registered for colorado 5.2.
name: colorado
title: Colorado
version: '5.2'
nav:
- modules/ROOT/nav.adoc (1)
- modules/la-garita/nav.adoc (2)| 1 | Registered navigation file for the ROOT module. |
| 2 | Registered navigation file for the la-garita module. |
The navigation file for the ROOT module contains one entry.
| 1 | A top-level entry referencing a page. |
The navigation file for the la-garita module contains two entries.
| 1 | A top-level entry. |
| 2 | A child entry of the previous top-level entry. |
Now, let’s look at the PDF produced for colorado 5.2 when section_merge_strategy is discrete.
The first page in the PDF is the title page. The title of the component, Colorado, is inserted as the title of the PDF (level 0 section title). The next page of the PDF is the start page of the component version. For colorado 5.2, the start page defaults to index.adoc in the ROOT module. Because the start page of the component version isn’t listed in a navigation file, it’s treated as a preface, and therefore, Asciidoctor PDF removes its page title by default.
The ranges.adoc page, the sole and top-level entry in the ROOT module’s navigation list, is the next page in the PDF. The title of the page is displayed in the PDF outline because the page is referenced in the navigation file. However, none of the page’s section titles, Primary ranges, etc., are listed in the PDF outline because the extension converted them to discrete headings.
The willow-creek.adoc page is appended to the index.adoc page of the la-garita module because it’s a child entry to the top-level entry for index.adoc in the la-garita navigation file. The titles of these two pages are displayed in the PDF outline because they’re entries in a navigation file.
enclose
The enclose value can be assigned to the section_merge_strategy key in the antora-assembler.yml file.
assembly:
section_merge_strategy: encloseWhen a top-level navigation entry references a page that contains a preamble, and enclose is assigned to section_merge_strategy, the following actions occur:
-
The section title Overview (or value assigned to the overview-title AsciiDoc attribute) is inserted between the page’s title and the preamble
-
Existing section titles on the top-level page become children of the new Overview section
-
An entry for the Overview section is inserted directly beneath the top-level entry as a child entry
-
Existing child entries of the top-level navigation entry become siblings of the new Overview entry
-
Entries referencing the section titles of a child page are inserted as children of the navigation entry for the child page; section title entries are inserted before any existing children of the navigation entry, effectively becoming siblings
| Whether the section title entries added to the navigation are displayed in the PDF outline or TOC of the generated PDF depends on the level Assembler assigns to a section while creating the assembly file and the toclevels and outlinelevels values. |
Let’s use the files in the la-garita module from the colorado 6.0 component version to demonstrate how enclose will impact the resulting PDF.
The navigation file for the la-garita module lists two files.
| 1 | A top level entry. |
| 2 | A child entry of the previous top level entry. |
The source content of the la-garita module’s index.adoc file contains a page title, preamble, and level 1, 2, and 3 section titles.
= La Garita Mountains
The La Garita Mountains are a subrange in the San Juan Mountains.
== La Garita Wilderness
The La Garita Wilderness is located in the La Garita Mountains.
It overlaps areas of the Gunnison National Forest and Rio Grande National Forest.
=== Trails
The wilderness area contains numerous backpacking trails as well as shorter trails, such as the xref:willow-creek.adoc[East Willow Creek trail].
==== Continental Divide Trail
A segment of the Continental Divide Trail is located in the La Garita Mountains.The source content of the willow-creek file also contains a page title, preamble, and level 1 section title.
= Willow Creek
Willow Creek runs through the town of Creede, CO.
== East trailhead
The La Garita and Phoenix peaks are accessible from the East Willow Creek trailhead.Now, let’s look at these pages in the PDF produced for colorado 6.0.
Notice that the section title Overview is inserted above the preamble in the index.adoc page. This title is also displayed in the PDF outline. However, because the willow-creek.adoc page is a child entry in the navigation file, an Overview section isn’t inserted between the page title and its preamble content.
If you activate the build.keep_source key and review the AsciiDoc source file Assembler creates for the PDF extension, you can see how Assembler inserts the Overview section and automatically recalculates the levels of the subsequent child and sibling section titles.
Example 11 shows a snippet of the assembly file produced when section_merge_strategy is enclose.
// ...
[#la-garita:index:::]
== La Garita Mountains
:!sectids:
=== Overview
:sectids:
The La Garita Mountains are a subrange in the San Juan Mountains.
[#la-garita:index:::wilderness]
==== La Garita Wilderness
The La Garita Wilderness is located in the La Garita Mountains.
It overlaps areas of the Gunnison National Forest and Rio Grande National Forest.
[#la-garita:index:::trails]
===== Trails
The wilderness area contains numerous backpacking trails as well as shorter trails, such as the <<la-garita:willow-creek:::,East Willow Creek trail>>.
// ...
[#la-garita:willow-creek:::]
=== Willow Creek
Willow Creek runs through the town of Creede, CO.overview-title attribute
When enclose is assigned to the section_merge_strategy key, the inserted section titles and their navigation entries are displayed as Overview by default.
This title can be changed with the overview-title AsciiDoc attribute.
In antora-assembler.yml, under the asciidoc and attributes keys, set overview-title and assign it your preferred title.
assembly:
section_merge_strategy: enclose
asciidoc:
attributes:
overview-title: Introductionfuse
The fuse value can be assigned to the section_merge_strategy key in the antora-assembler.yml file.
assembly:
section_merge_strategy: fuseThe fuse value inserts entries referencing the section titles of a page as children of the navigation entry for the page.
The entries are inserted before any existing children of the navigation entry, effectively becoming siblings.
Whether the section title entries added to the navigation are displayed in the PDF outline or TOC of the generated PDF depends on the level Assembler assigns to a section while creating the assembly and the toclevels and outlinelevels values.
Let’s use the navigation file shown in Example 14 for the la-garita module from the colorado 6.0 component version to demonstrate how fuse will impact the resulting PDF.
The navigation file for the la-garita module lists two files.
The entry for the willow-creek.adoc file is a child of the index.adoc entry.
The index.adoc source content in Example 15 contains a page title and level 1, 2, and 3 section titles.
= La Garita Mountains
The La Garita Mountains are a subrange in the San Juan Mountains.
== La Garita Wilderness
The La Garita Wilderness is located in the La Garita Mountains.
It overlaps areas of the Gunnison National Forest and Rio Grande National Forest.
=== Trails
The wilderness area contains numerous backpacking trails as well as shorter trails, such as the xref:willow-creek.adoc[East Willow Creek trail].
==== Continental Divide Trail
A segment of the Continental Divide Trail is located in the La Garita Mountains.Let’s look at the resulting PDF outline when section_merge_strategy is fuse using the navigation file in Example 14 and index.adoc and willow-creek.adoc files as inputs.
The section title La Garita Wilderness from index.adoc is inserted as a child entry into the navigation, and therefore the PDF outline and TOC (if activated). The child navigation entry for the willow-creek.adoc page becomes a sibling of the La Garita Wilderness entry.
profile
The settings defined in the Assembler configuration file are the defaults for all component versions.
These defaults can be overridden per component version using the assembler subkey under the ext key in the component version descriptor.
These overrides are organized in that file by profile.
The optional profile key in the Assembler configuration file controls which profile from the component version descriptor is selected.
The profile key is an optional key that can be set in antora-assembler.yml.
It accepts a String value.
The default value for the profile key is the converter backend defined by the exporter extension.
For the PDF extension, this value is pdf.
The component version descriptor can define a default profile, which is a profile with no name. If the named profile is not found in the component version descriptor, the default profile is used, if present. Only the keys defined in the profile override the global settings. If no profile is matched, Assembler only uses its global settings.
Here’s an example of how the profile can be specified in the Assembler configuration.
assembly:
profile: handpicked-pdfsHere’s the matching profile defined in the component version descriptor:
ext:
assembler:
- profile: handpicked-pdfs
root_level: 1
insert_start_page: false
nav:
- modules/ROOT/nav-handpicked-pdfs.adocWhen using the PDF extension, unless you have multiple PDF profiles, you could just name the profile pdf and leave the profile key unset in the Assembler configuration file (which will then default to pdf).