Configure AsciiDoc

To add a Table of Contents to each export (e.g., PDF), set the toc attribute in antora-assembler.yml.

The pdf-theme attribute is used to activate and apply a custom theme when converting to PDF. The pdf-theme attribute accepts the name of a YAML file stored in your playbook directory. In this example, the file is named pdf-theme.yml.

Image attributes are a unique feature of Asciidoctor PDF and Asciidoctor EPUB that allow images to be configured using an image macro in an attribute. Assembler recognizes and processes the value of these image attributes so the converter can resolve the image.

If the name of a global AsciiDoc attribute ends with -image (e.g., title-logo-image) and the value of that attribute is an image macro (e.g., image:the-component::logo.png[] whose target is an Antora resource reference, Assembler will resolve the resource, copy that file into the build directory, and rewrite the target of the macro so the converter (e.g., Asciidoctor PDF) can locate it. (A global AsciiDoc attribute is one defined in the Antora playbook, component version descriptor, or Assembler configuratio file). In other words, if an attribute name ends with -image, the target of the image macro in the value can be an Antora image reference. Since Assembler runs outside the context of any component, the resource reference must be fully qualified, meaning it must start with a component name.

If the image target does not match the resource reference syntax (meaning it’s a URL or otherwise does not contain a colon), then the target is resolved as is. If the target is a relative path, the path is resolved starting from the value of the intrinsic imagesdir attribute, which is the Assembler build directory.

Here’s an example of how to use an image from the site as the logo image on the title page (for converters that support it).

Refer to Logo image to learn more about how to use the title logo image with Asciidoctor PDF.

Keep in mind that this feature only works when using image attributes. It’s not possible to define an image whose target is an Antora resource reference in the Asciidoctor PDF theme file. The value of these theme keys is not processed by Assembler.

If a rewritten ID starts with a character other than a letter, underscore, or colon, Assembler must add a prefix in order to make the ID valid. By default, this prefix is _. If you want to use a different prefix, you can specify it in the Assembler configuration using the assembler-idprefix attribute.

Note that this prefix is not added to all IDs, only when necessary.

By default, Assembler uses the navtitle as the starting section for a page in the assembly as well as the subtitle for the assembly when root level is 1. If you want to use a different navtitle in the assembly than what’s defined in the navigation, you can assign the assembly-navtitle attribute in the document header of the page. For example:

The value of the assembly-navtitle works just like the navtitle attribute, except it’s used by Assembler (and always takes precedence). Note that changing the navtitle also impacts the filename of the assembly when the rootLevel is 1.

The assembly-navtitle attribute is not propogated to the assembly document.

By default, the filename of the export is generated automatically. When root level is 0, the filename stem (the part without the file extension) is index. When root level is 1, the filename is generated from the navtitle of the assembly.

You can use the assembly-slug attribute on the root page to override the filename of of the export. The slug must only contain letters, numbers, underscores, hyphens, and periods. Any spaces are replaced with hyphens. All other characters are removed.

If the assembly-slug attribute is not defined in the root page of the assembly, it is ignored. The assembly-slug attribute is not propogated to the assembly document.

Assembler controls the header of the assembly document, populating it with a fixed set of attribute entries. It’s possible to add additional attribute entries by promoting them from the root page using assembly-header-attributes. This feature is intended for attributes that are used as metadata or settings, such as revnumber, revdate, title-logo-image, etc.

The root page is defined as the top-level page in the navigation outline to defines the assembly. When root_level is 0, this is typically the component version start page. When root_level is 1, this is the page referenced by each top-level navigation item.

The root page can promote attributes in its own header to the assembly header using the assembly-header-attributes attribute. This attribute accepts a comma-separate list of attribute names. For example:

Note that the attribute url-example is not promoted and thus only visible within the merged page.

If you don’t want revdate to be set, you can unset it in the page header. You can also unset any other attribute as long as its value is soft set in the configuration, such as title-logo-image.

The assembly-header-attributes also accepts the special attribute name %authors, which promotes all the author-related information to the header. For example:

If the assembly-header-attributes attribute is not specified, it defaults to %authors. The assumption is that the authors defined on the root page are the authors for the assembly. If you don’t want any attributes to be promoted, set the value of the attribute to empty.

The reason that all attributes are not promoted is that it would alter the scope of those attributes, leading to dependency on the broader scope of the attribute in the assembly that’s not present in the page.

PDF isn’t the only output format that Assembler can generate. That’s a choice of the exporter extension and its build command. Therefore, when Assembler is constructing the assembly, the Asciidoctor backend is not set to pdf as you might expect. Rather, the backend is still html5.

In other words, there are multiple processing phases. The first phase is when Assembler is reducing the individual pages and merging them to produce the assembly. During the phase, the backend is still html5. The second phase is when Assembler converts the assembly to the output format, such as PDF. During this phase, the backend matches the output format, such as pdf.

Thus, if you want to include or filter out content when Assembler is producing the assembly, you cannot rely on the backend attribute. Instead, you need to make use of the built-in loader-assembler attribute (or any other attribute you set in the Assembler configuration file). The loader-assembler attribute is set in both phases.

Thus, if you only want to include content in the PDF, you can test for the loader-assembler attribute as follows:

To exclude content in the PDF, you can test for the absence of the loader-assembler attribute as follows:

Alternately, you can use one of the intrinsic attributes set by Assembler that hint at which converter is being used and which assembly profile is active. For example:

If you want to include content in the assembly, but not when converting to PDF, then you can test for assembler-backend-pdf inside this conditional.

Other permutations are available as well.

It’s currently not possible to use a backend attribute in a preprocessor conditional since conditionals are evaluated during assembly, before the AsciiDoc is converted. Thus, they don’t have the indented effect.