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 configuration. You can configure which additional AsciiDoc attributes are set by Assembler using the assembly category key in the Assembler configuration.

attributes key

See attributes key.

Intrinsic attributes

In addition to the attributes specified in the configuration, several intrinsic attributes are set by Assembler. These attributes, along with their default values, are listed in the following table.

Attribute Name	Default Value	Example Assignment
doctype	book	doctype=book
revdate	<local date>	revdate=2025-01-01
page-partial	empty	page-partial=
loader-assembler	empty	loader-assembler=
assembler-backend	<target backend>	assembler-backend=pdf
assembler-backend-<backend>	empty	assembler-backend-pdf=
assembler-profile	<target backend>	assembler-profile=pdf
assembler-profile-<profile>	empty	assembler-profile-pdf=

Attribute Name

Default Value

Example Assignment

doctype

book

doctype=book

revdate

revdate=2025-01-01

page-partial

empty

page-partial=

loader-assembler

empty

loader-assembler=

assembler-backend

assembler-backend=pdf

assembler-backend-<backend>

empty

assembler-backend-pdf=

assembler-profile

assembler-profile=pdf

assembler-profile-<profile>

empty

assembler-profile-pdf=

If you don’t want the revdate to be set in the assembly, you can soft (or hard) unset it in the Assembler configuration:

Example 1. antora-assembler.yml

assembly:
  attributes:
    revdate: false

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 contains & that’s not preceded by a space and the command starts with bundle exec, the ampersand will be escaped using ^{^}. These escape characters will not be present in the attribute value once the processor receives it.

Resource references

Any xrefs in the merged set of attributes are rewritten relative to that assembly (just like an xref in a page). All other references (e.g., images) in the merged set of attributes for an assembly are rewritten relative to the component version.

When Assembler rewrites a reference to a page that is included in the assembly, it converts it from an interdocument xref to an internal xref. In other words, the target of the reference becomes an ID (within the assembly) rather than a resource. If you want the reference to use automatic cross reference text, then no explicit text can be specified in the original xref (e.g., xref:install.adoc[]).

If the reftext attribute is defined on the page, then it gets used (by the converter) as the text of the reference and the xrefstyle will not be honored. If you want the xrefstyle to be honored, only define the reftext attribute outside the scope of Assembler. For example:

[reftext=The Reference Text]
= The Page Title

See Conditional content for more details about how to use conditionals to control what content is used in the assembly.

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

assembly:
  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

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

Image references

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

Example 4. antora-assembler.yml

assembly:
  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.

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.

Override ID prefix

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.

Example 5. antora-assembler.yml

assembly:
  attributes:
    assembler-idprefix: anchor-

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

Override navtitle

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 a non-empty value to the assembly-navtitle attribute in the document header of the page. For example:

= The Page Title
:navtitle: Page Title
:assembly-navtitle: Page Title in Assembly

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. Instead, it’s value is used as the title of the corresponding section.

If your intent is to hide the title in the assembly, set the notitle option on the page header instead.

Override filename

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. To generate the filename, the navtitle is converted to lowercase, HTML tags are removed, character references are converted to characters, quotes are removed, underscores and periods are replaced with hyphens, and any characters other than letters, numbers, or hyphens are dropped.

You can use the assembly-slug attribute on the root page to override the filename of of the export.

= The Manual
:assembly-slug: manual

The slug must only contain letters, numbers, underscores, periods, and hyphens. Any invalid characters (including spaces) are replaced with hyphens. Leading and trailing hyphens are removed and repeating hyphens are condensed.

The assembly-slug permits underscores and periods, whereas the auto-generated slug does not.

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.

If you prefer, you can change the filename of the export using an Antora extension instead. Let’s move all root level 0 exports to the top-level of the site and use the pre-computed download value as the filename.

We’ll leverage the createFile method on the content catalog (introduced in Antora 3.2.0) to compute the out and pub properties, then assign those to our export. The benefit of using createFile is that it works out all the details with the latest and prerelease version segments, where applicable. By modifying the out and pub properties, we ensure that the link to the export from the UI will remain intact.

Since we’re listing for the navigationBuilt event, this extension must be registered after the exporter extension.

module.exports.register = function () {
  this.once('navigationBuilt', ({ contentCatalog }) => {
    const exportFiles = contentCatalog.findBy({ family: 'export' }).filter((it) => {
      return it.src.stem === 'index' && it.assembler?.rootLevel === 0
    })
    for (const exportFile of exportFiles) {
      const newFile = contentCatalog.createFile({
        src: { component: 'ROOT', version: '', module: 'ROOT', family: 'export', relative: exportFile.pub.download },
      })
      Object.assign(exportFile, { out: newFile.out, pub: newFile.pub })
    }
  })
}

If you want to eliminate the _exports directory from the output path and URL, you will need to further manipulate the properties on out (dirname, path, moduleRootPath, and rootPath) and pub (url, moduleRootPath, and rootPath).

Promote attributes to header

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:

= The Project
:revnumber: 1.0-GA
:revdate: 2026-01-01
:url-example: https://example.org
:assembly-header-attributes: revnumber,revdate

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 Project
:revnumber: 1.0-GA
:!revdate:
:!title-logo-image:
:url-example: https://example.org
:assembly-header-attributes: revnumber,revdate,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:

= The Project
Project Team <info@project.example.org>
:revnumber: 1.0-GA
:revdate: 2026-01-01
:url-example: https://example.org
:assembly-header-attributes: %authors,revnumber,revdate

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.

Use root page as book preface

The whole root page (typically the start page) serves as the book preface by default when the root level is 0. You can change this default, or enable it in other cases, using the assembly-style attribute. The preface-title (or assembly-navtitle) attribute can be used to set a title for the preface.

If the assembly-style is not specified on the root page and the root level is 0, the whole page serves as the preface; the title is retrieved from the preface-title attribute, if defined (set or unset), otherwise the computed navtitle.
If the preface-title attribute is set on the preface root page (even if empty), and the page has no sections or block attributes, the preface-title attribute is automatically promoted to the header in lieu of making a preface section.
If the preface root page has sections or block attributes, a dedicated preface section is introduced instead of the preface-title attribute being promoted. If present, the sections are shifted down a level.

Here’s an example of the start page for a root level 0 assembly acting as the book preface:

= Start Page
:preface-title: Introduction

This is the book preface.

If, instead, you want to promote the top-level sections on the root page to chapters, unset the assembly-style attribute. In this case, any top-level sections are promoted to chapters (effectively leveloffset -1). Any content above the first section becomes the implicit preface (in which case the preface-title is still relevant for the converter).

Here’s an example of the start page for a root level 0 assembly that contributes chapters. The example also shows how to customize the preface title in this scenario.

= Start Page
:preface-title:
:!assembly-style:
:assembly-header-attributes: preface-title

This is the book preface.

== First Chapter

Note that when root level is 1, the root page must be explicitly marked as a preface using the assembly-style attribute in order for the whole page to serve as the book preface.

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.

Conditional directives are only reevaluated for Assembler in a nav file when that nav file is specified in an assembly profile. Refer to the section about alternate navigation on the assembly profiles page to learn more.

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.