Antora’s Site Generation Process
Antora’s default site generator handles all aspects of creating a documentation site, from fetching and aggregating to converting and arranging the content to publishing the files of the generated site. This page describes that process in detail.
The default pipeline is opinionated to get you started as quickly as possible. But understand that Antora features a modular, open architecture. That means this architecture can accommodate specialized use cases by allowing custom components, such as a validators, to be inserted into the pipeline at strategic points as needed. This page focuses on the core, built-in components and capabilities in Antora.
The steps listed in this section describe the operations the default site generator performs. Certain operations are executed asynchronously, so some of the steps below may occur in a different order or happen simultaneously. For example, the UI is fetched and loaded while the content is being aggregated to optimize use of the network.
- Build playbook
When you’re ready to generate a site, you pass Antora a playbook file and tell it to run.
A playbook file is simple a configuration file that can be written in YAML, JSON, or TOML. It contains information and settings such as what content to use, how the content should be processed, how the site should be generated, and where to publish the output.
Antora reads the playbook file and builds a playbook from it, which it then uses to drive the pipeline.
- Load content repositories
Using the content sources listed in the playbook, Antora loads the specified git repositories or local content folders in preparation to scan them for content files.
For each remote URL, Antora clones the remote git repository into a local cache using the built-in git client. If the repository has already been cloned, Antora fetches updates if configured to do so.
Finally, Antora determines which references (branches and/or tags) to use from the specified repositories.
- Find the documentation component in each selected branch and/or tag
Antora identifies a group of files as a documentation component when it finds a component descriptor file named antora.yml.
A documentation component is a set of files that are versioned together and usually share a common subject, such as all of the content source files for a software product. Component source files can be stored in a single repository, at the root of a repository or in a subpath, or distributed across multiple repositories.
- Transform input files into virtual file objects
Antora collects all of the files—text, images, samples, and other supporting materials—from each documentation component subtree. Then it creates a virtual file of each input file.
- Assign files to component-version collections
Antora reads the component descriptor (i.e., antora.yml) files.
A component descriptor associates the files under it with a specified component name and version (aka component-version). This allows the files to be decoupled from the repository and branch in which they live. The component descriptor file makes Antora’s repository-spanning, file system and URL agnostic cross references possible.
Antora assigns the descriptor information and other source metadata to the appropriate virtual files. Then it sorts each file into a virtual collection based on the assigned component-version data.
- Compute additional metadata
Using site properties from the playbook and information assigned to the files in the previous step, Antora adds module, family, family-relative path, and other metadata values to each file. It also computes the output path (disk) and publish path (URL) information for each publishable file.
- Organize files into a content catalog
Antora further sorts the aggregated files into a content catalog that can be queried and transmitted.
- Convert AsciiDoc files to embeddable HTML
The AsciiDoc files in the page family of the content catalog are converted to embeddable HTML with Asciidoctor.js.
- Convert navigation files
Antora retrieves navigation files from the content catalog, translates their contents into navigation items organized in a specified hierarchy (navigation trees grouped inside a navigation menu), and returns a navigation model.
- Locate and fetch UI bundle
Antora finds the UI bundle using the URL listed in the playbook and fetches it. The UI bundle can be cached locally or remote.
- Transform UI files into virtual file objects
Antora extracts the UI files in the bundle and creates a virtual file object for each file containing the file’s contents and path information.
- Classify UI files
Antora identifies the static UI files using the UI descriptor file (ui.yml) and sets the file type to static. It sets the type for all other files based on their location (asset, layout, helper, partial).
- Compute UI file output paths
For each UI file that is publishable (of type static or asset), Antora computes its output path.
- Organize UI files into UI catalog
The virtual UI files are sorted into a transmittable collection.
- Wrap converted AsciiDoc content in page templates
Antora determines which page template each page requests. It populates the identified UI template with the page’s embeddable HTML, site metadata, context data (component, version) for page, version, and product selectors, and navigation model information for menus and breadcrumbs.
Relying on a page template to produce the pages gives the site owner complete control over the construction of the pages, and thus complete control over the UI.
- Produce sitemap
Antora generates a site map that can be used as an internal report or published with the site. This sitemap is partitioned by component (using a sitemap index). The sitemap index links to the sitemap for each component, which is where the URLs for the individual pages can be found.
- Publish site
Antora writes the generated pages to a default or user-specified location. The site can be published in multiple formats to multiple locations over multiple protocols using built-in and custom destination providers.
It’s possible to substitute this pipeline (the default site generator) with a custom one.
You first need to create a library or script that exports the function with signature
Within that script, you’re free to import core components from Antora to reassemble your own pipeline.
You then activate your pipeline by passing the name of the library or script to the
--generator option of the Antora CLI.