Configure AsciiDoc

By default, Assembler passes all attributes that are set on a component version to the AsciiDoc processor when reducing AsciiDoc documents. It also passes these attributes to the converter so they are set when the assembly is converted to the target format. Assembler allows additional attributes to be specified (set or unset) using the AsciiDoc configuration.

You can configure which additional AsciiDoc attributes are set by Assembler using the asciidoc category key in the Assembler configuration.

asciidoc key (category)

The asciidoc 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
`attributes`	<not set>	Map	Additional AsciiDoc document attributes that are assigned when reducing AsciiDoc documents and converting the assembly to the target format.

attributes

Map

Additional AsciiDoc document attributes that are assigned when reducing AsciiDoc documents and converting the assembly to the target format.

attributes key

The attributes key accepts a map (name: value pairs) of additional attributes to pass to the AsciiDoc processor when reducing, assembling, and converting files to the target format. These attributes supplement attributes defined in the playbook, component version descriptors, and pages. See Assign Attributes to a Site for precedence rules.

Example 1. antora-assembler.yml

asciidoc:
  attributes:
    secnums: ''
    xrefstyle: full
    outlinelevels: '2'

Intrinsic attributes

In addition to the attributes specified in the configuration, several intrinsic attributes are set by Assembler.

If the doctype is not specified, it defaults to book. If the revdate is not specified, it defaults to the local date. The page-partial attribute is unset. The loader-assembler attribute is automatically set to an empty value. The assembler-backend attribute is set to the target backend and the assembler-backend-<value> attribute is set to an empty value. The assembler-profile attribute is set to the profile (which defaults to the converter backend) and the assembler-profile-<value> attribute is set to an empty value.

Portability considerations

If any attribute that Assembler passes to the command contains a non-ASCII character, you must enable UTF-8 support on Windows or else the command will fail. See Using UTF-8 in the Windows Terminal to learn different ways of activating this support. It may also be necessary to set the code page in the terminal to UTF-8 using chcp 65001.

On Windows, if the attribute value begins with & and the command starts with bundle exec, a space will be inserted at the start of the value. There’s no other way we know of to prevent cmd.exe from choking on the attribute argument in this scenario. It’s still possible to use an Asciidoctor extension to trim the attribute value once inside of the Asciidoctor runtime.

Use cases

Enable the TOC

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

Example 2. antora-assembler.yml

asciidoc:
  attributes:
    toc: ''

Activate a custom PDF theme

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.

Example 3. antora-assembler.yml

asciidoc:
  attributes:
    pdf-theme: ./pdf-theme.yml

Image references

If the name of a document 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[], Assembler will automatically resolve the target as an Antora reference, copy that file into the build directory, and rewrite the target of the macro so the converter (e.g., Asciidoctor PDF) can locate it. In other words, if the document attribute ends with -image, the target of the image macro can be an Antora image reference. However, since Assembler runs outside the context of any component, the reference must be fully qualified, meaning it must start with a component name.

Here’s an example of how to set the logo image on the title page when using Asciidoctor PDF to generate the PDF:

Example 4. antora-assembler.yml

asciidoc:
  attributes:
    title-logo-image: image:the-component::logo.png[pdfwidth=1in]

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

Conditional content

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:

ifdef::loader-assembler[]
This content will only appear in the PDF.
endif::[]

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

ifndef::loader-assembler[]
This content will only appear in the site.
endif::[]

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:

ifdef::assembler-backend-pdf[]
This content will only appear in the PDF.
endif::[]

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.

ifdef::loader-assembler[]
ifndef::assembler-backend-pdf[]
This content will only appear in the assembly, but not when converting to PDF.
ifndef::[]
endif::[]

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.