Antora Assembler Documentation

Antora Assembler (herein, Assembler) provides a JavaScript library and a set of Antora extensions for exporting content in an Antora site to PDF and other formats. If you are looking to create PDFs using the content from your site, the Antora PDF extension, Assembler’s built-in PDF exporter extension, is the software you’re looking for. Yet, Assembler is not just limited to creating PDFs.

The core of Assembler handles merging AsciiDoc content from multiple pages into an assembly. It repeats this process for each selected component version. It then delegates to a function or command (e.g., asciidoctor-pdf) designated by an exporter extension to convert the assembly files to an export format, such as PDF, resulting in an export. Assembler then publishes the export files along with the other files in the site.

Features

Antora Assembler provides the following capabilities and features:

  • Combines AsciiDoc content from multiple pages based on the navigation model.

  • Rewrites IDs to avoid conflicts across pages.

  • Reconciles the navigation and section hierarchies.

  • Rewrites references to decouple them from the Antora referencing system, making them standard AsciiDoc.

  • Can be applied to selection of components and versions using a pattern-based filter.

  • Allows the navigation to be customized per export format or profile.

  • Allows content and navigation to be filtered using preprocessor conditionals.

  • Provides different strategies for combining the navigation hierarchy with the section hierarchy of each page.

  • Delegates to an external command to convert the AsciiDoc assemblies to the target format.

  • Supports configuring the converter command using AsciiDoc attributes or CLI option flags.

  • Can be used to export to various formats using different exporter extensions.

  • Establishes a link from each page included in an assembly to the export in which it is included.

  • Provides an API for writing new exporter extensions or calling Assembler programmatically.

Assumptions

Assembler is designed to create exports from content (i.e., pages and navigation) in an Antora site. That means your content must already be organized in Antora content roots (i.e., the Antora standard file hierarchy) and you must have an Antora playbook file that itemizes those content roots. Assembler runs during Antora site generation.

If you have organized your content for use with Antora, you will not be able to run an AsciiDoc converter (e.g., Asciidoctor PDF) on that content as is. That’s because AsciiDoc converters do not understand Antora’s structure, references, or scoping. Assembler provides that bridge. Assembler prepares the AsciiDoc source so it can be converted using any AsciiDoc converter.

Although Assembler is designed to publish the exports along with the site, you can use it merely as a tool to produce those exports without publishing them.

Packages

The Assembler project distributes the following packages:

Assembler Core (@antora/assembler)

Assembler is a JavaScript library for writing Antora extensions that merge content from multiple pages into a single output file. The assembly files that Assembler produces are Antora-agnostic, which means they can be converted by any AsciiDoc converter, such as Asciidoctor PDF. Assembler uses the converter metadata and convert function provided by the exporter extension to convert the assembly files to the target format.

Antora PDF Extension (@antora/pdf-extension)

The Antora PDF Extension is the official extension for producing PDFs from content in an Antora site. It generates PDFs from assembly files prepared by Assembler Core. It does so by configuring Assembler and passing it a converter (metadata and convert function). Assembler Core manages the rest of the workflow.

EPUB and HTML (single) extensions are planned.

Assembler Core is installed automatically when you install the Antora PDF Extension, the latter which serves as an entry point for Assembler.

Operation

The user-facing part of Assembler is the exporter extension (e.g., @antora/pdf-extension). The exporter extension configures Assembler—​essentially creating an instance of Assembler—​and provides the converter to handle conversion to the target format. From there, Assembler creates the assembly file, calls the converter provided by the exporter extension, such as Asciidoctor PDF, to convert the assembly files to the target format, then publishes those converted files as exports (i.e., export family) in the Antora site.

When Assembler creates the assembly files, it models them using the navigation structure. In other words, it uses the navigation to know which pages to merge, and which order to merge them in.

An Assembler instance can either produce a single export from a component version, or an export per top-level navigation entry. When assembling content, Assembler rewrites all references in the Antora referencing system to decouple them from Antora while also avoiding ID conflicts.

Currently, each target format you want to produce requires the use of a dedicated exporter extension. The exporter (assembly and conversion) is controlled through the use of an Assembler configuration file (e.g., antora-assembler.yml). Typically, an exporter will use an external command to handle the conversion, so you can conveniently plug in and configure the AsciiDoc converter of your choice.

Next steps

To get an idea of how Assembler works and what you can accomplish with it, refer to Core Concepts. You can get started with Assembler by installing and registering an exporter extension. You’ll then be ready to learn how to export content in your site using an Assembler instance by way of an exporter extension. Refer to Configuration Tutorial to find a full walkthrough.