Configure the Build

Assembler sets up a build directory in which to run the command to convert the AsciiDoc source of the assembly to the target format. The target format and file extension, as well as the default command, are provided by the exporter extension. Assembler allows the command to be overridden using the build configuration.

You can configure how the build directory is prepared, which command to run, whether to publish the result, and other related settings using the build category key in the Assembler configuration.

build key (category)

The build category key is an optional key that can be set in the Assembler configuration file (e.g., antora-assembler.yml).

Acceptable keys and their default values are listed in the table below.

Key Default Type Description

Key	Default	Type	Description
`command`	<set by exporter> asciidoctor-pdf for the PDF extension	String (shell command with optional space-separated list of arguments)	The external converter command to invoke to convert AsciiDoc source documents compiled by Assembler to the target format.
`clean`	false	Boolean	Controls whether the directory specified by the `dir` key should be removed before Assembler runs.
`dir`	./build/assembler-<profile>	String (absolute path, path relative to start path if starts with ./, or path relative to content source root)	The temporary directory Assembler uses to prepare and generate the export files.
`mkdirs`	false	Boolean	Controls whether the output directory of the export (under the build directory) should be created eagerly, or whether it should be left up to the command.
`keep_souce`	false	Boolean	Controls whether the assembly source files should be kept under the build directory for debugging purposes (images are always kept).
`process_limit`	auto (half the number of CPUs)	Integer, auto, or false	Sets the number of concurrent processes that Antora should not exceed when invoking the converter command.
`publish`	true	Boolean	Whether to publish the export files with the site alongside the HTML files.
`qualify_exports`	false	Boolean	Whether to qualify the filename of the export files with the component name and version.

command

<set by exporter> asciidoctor-pdf for the PDF extension

String (shell command with optional space-separated list of arguments)

The external converter command to invoke to convert AsciiDoc source documents compiled by Assembler to the target format.

clean

false

Boolean

Controls whether the directory specified by the dir key should be removed before Assembler runs.

dir

./build/assembler-<profile>

String (absolute path, path relative to start path if starts with ./, or path relative to content source root)

The temporary directory Assembler uses to prepare and generate the export files.

mkdirs

false

Boolean

Controls whether the output directory of the export (under the build directory) should be created eagerly, or whether it should be left up to the command.

keep_souce

false

Boolean

Controls whether the assembly source files should be kept under the build directory for debugging purposes (images are always kept).

process_limit

auto (half the number of CPUs)

Integer, auto, or false

Sets the number of concurrent processes that Antora should not exceed when invoking the converter command.

publish

true

Boolean

Whether to publish the export files with the site alongside the HTML files.

qualify_exports

false

Boolean

Whether to qualify the filename of the export files with the component name and version.

command key

The command key accepts a shell command that runs the AsciiDoc converter to convert the source documents compiled by Assembler to the target format (e.g., PDF). The command runs in the context of the environment in which Antora was launched.

The AsciiDoc source to convert isn’t written into the build directory. Instead, it’s passed to the command via the stdin channel.

The default value of command is controlled by the exporter. For the PDF extension, the value is asciidoctor-pdf (and prefixed with bundle exec if Gemfile.lock is detected).

If you’re using Bundler to manage gems, and you want to customize the command, make sure you prefix the command with bundle exec.

Example 1. antora-assembler.yml

build:
  command: bundle exec asciidoctor-pdf

On Windows, Assembler will automatically run the command in a shell (using cmd.exe) if the command is a batch script. This method of invocation is required by Node.js.

Specifying the command key gives you an opportunity to pass CLI options to the command. Use the -r option to require additional libraries, such as asciidoctor-kroki.

Example 2. antora-assembler.yml

build:
  command: bundle exec asciidoctor-pdf -r asciidoctor-kroki

When using the Asciidoctor Kroki extension in Assembler, you must set the allow-uri-read attribute and unset the kroki-fetch-diagram attribute. That’s because Kroki does not fetch diagrams to a location where the assembly created by Assembler can resolve. Instead, the diagram has to be read directly from the Kroki URL.

If you want Asciidoctor PDF to print the full backtrace of an error for debugging purposes, add the --trace option. If you want Asciidoctor PDF to report the file and line number for warnings when available (hence more accurate diagnostic messages), add the --sourcemap option.

Example 3. antora-assembler.yml

build:
  command: bundle exec asciidoctor-pdf --trace --sourcemap

You can also pass additional attributes not defined in the Assembler configuration using the -a option. This is a good way to enable the source highlighter.

Example 4. antora-assembler.yml

build:
  command: bundle exec asciidoctor-pdf -a source-highlighter=rouge

Run bundle exec asciidoctor-pdf -h to get a list of available options. Not all options are applicable in this environment (such as -D).

clean key

The clean key controls whether the directory specified by the dir key should be removed before Assembler runs. By default, this key is assigned the value of the output.clean key in the playbook, if specified. Otherwise, it’s assigned the value false.

Example 5. antora-assembler.yml

build:
  clean: false

This key should only be set when using multiple extension instances since leaving behind generated and staged files from a previous run can lead to unexpected and non-reproducible behavior.

dir key

The dir key specifies the directory Assembler uses to prepare and build the exports. By default, the build directory is ./build/assembler-<profile>, where <profile> is the value of the profile key if set, otherwise the converter backend set by the exporter extension (e.g., pdf).

The dir key accepts a directory path and uses the same path resolution rules as the output directory in the Antora playbook.

Example 6. antora-assembler.yml

build:
  dir: ./build/pdfs

When using multiple exporter extensions in the same Antora run, it’s important to ensure the build.dir key is unique.

mkdirs key

The mkdirs key tells Assembler to create the directory where the command specified in the command key is going to write the output file. By default, this key is assigned the value false. To have Assembler create the output directory and any intermediary directories leading up to it automatically, assign the value true to mkdirs key in antora-assembler.yml.

Example 7. antora-assembler.yml

build:
  mkdirs: true

This key should be set to true if the command is not capable of creating the directory for the output file itself.

keep_source key

The keep_source key indicates whether the assembly source files under the build directory should be kept (images are always kept). By default, this key is assigned the value false and the assembly source file is not written to the build directory.

To keep these intermediate source files, which may be helpful when debugging certain issues, assign the value true to keep_source in antora-assembler.yml.

Example 8. antora-assembler.yml

build:
  keep_source: true

In the above example, the assembly source files and referenced images will be located under path assigned to the dir key. If you’re using the default build directory (./build/assembler-<profile>), they’ll be located under that directory.

process_limit key

The process_limit key sets the number of concurrent processes that Antora should not exceed when calling the command to convert the AsciiDoc source of each assembly file. It accepts the value auto, a positive integer, or a falsy value (including 0).

Example 9. antora-assembler.yml

build:
  process_limit: 2

The default value is auto, which resolves to half the number of available CPUs. Use a falsy value (e.g., false, 0, or ~) to remove the limit.

publish key

The publish key indicates whether to publish the export files to the output destination(s) of the site alongside the HTML files. This key accepts the values true or false. The default value is true, which means the export files are published to the site’s output destination(s).

If you want the PDF extension to generate the exports (e.g., PDFs) into the build directory, but not publish them to the site’s output destination(s), set the value of the publish key to false in your antora-assembler.yml file:

Example 10. antora-assembler.yml

build:
  publish: false

If publish is assigned the value false, the export files are still generated and written to the build directory, but they will not be published to the site.

If you want Assembler to generate the exports, but you don’t want Antora to publish the site during the same run, set the destinations key under the build category to an empty array ([]) in your Antora playbook file (antora-playbook.yml).

Example 11. antora-playbook.yml

output:
  destinations: []

You’ll still find the PDFs generated by the PDF extension under Assembler’s build directory.

If you don’t want Assembler to generate the export files at all, set the command to 'true' (including the quotes). You might want to do this if you are only interested in creating the assembly source.

Example 12. antora-assembler.yml

build:
  command: 'true'
  publish: false

On *nix, you can set the command to /bin/true instead.

An alternative to using the command 'true' is to create an empty shell and batch script and reference it in the command key. In this case, the publish key must also be set to false to prevent Assembler from looking for the generated files.

qualify_exports

The qualify_exports key indicates whether to qualify the filename of the export with the component name and version when publishing it to the site. (This qualifier does not impact the export’s resource ID). This key accepts the values true or false. The default value is false, which means the export files are not qualified.

The URL to which the export is published is already unique and thus qualified. However, when the export is downloaded, such as a PDF, the browser only uses the basename (the last segment of the URL). This situation introduces a naming conflict in the download folder. Furthermore, the filename may not be descriptive enough (e.g., index.pdf) for the user to recognize it.

This problem can be alleviated by enabling the qualify_exports setting.

Example 13. antora-assembler.yml

build:
  qualify_exports: true

When this setting is enabled, the published filename will start with the component and (actual) version. If the root level is 0, the filename will be <component>-<version>.<extname> instead of index.<extname>. If the root level is 1, the filename will be <component>-<version>-<slug>.<extname> instead of <slug>.<extname>.