Generator Lifecycle Events Reference

Antora extensions listen for events emitted by the generator when Antora runs. Each listener can access variables that are in scope at the time the event is emitted. The following table lists the generator events in the order they’re emitted and the context (in-scope) variables that correspond to each event. If the variable is locked, meaning it cannot be replaced, it’s italicized.

Table 1. Antora extension events and in-scope variables
Event name	In-scope variables
register()^[1]	playbook, config
contextStarted^[2]	playbook
playbookBuilt	playbook
beforeProcess	playbook, siteAsciiDocConfig, siteCatalog
contentAggregated^[3]	playbook, siteAsciiDocConfig, siteCatalog, contentAggregate
uiLoaded^[3]	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog
contentClassified	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog
documentsConverted	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog
navigationBuilt	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog, navigationCatalog
pagesComposed	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog
redirectsProduced	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog
siteMapped^[4]	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog
beforePublish	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog
sitePublished	playbook, siteAsciiDocConfig, siteCatalog, uiCatalog, contentCatalog, publications
contextStopped	(any variable still in scope at the time the context is stopped)
contextClosed^[5]	(any variable still in scope at the time the context is closed)

The playbook object (i.e., the parsed data from the playbook file) is available at the time the register function is called (which acts like the register event). However, at this stage, the playbook is still just a raw data model. The Antora extensions have yet to be registered. When the contextStarted is emitted, all the initialization of the playbook, including registering Antora extensions and generator functions, is complete.

When modifying the content sources in an Antora extension, it’s customary to use the playbookBuilt event. After that, the playbook object cannot be modified or updated.

In addition to the built-in context variables listed in this table, your extension can also access context variables documented and promoted by other extensions.

1. The register function isn’t an event, but rather the function Antora calls on an extension so it can register listeners.

2. The built-in generator functions are not available until this event is emitted.

3. The order of the contentAggregated and uiLoaded events relative to each other is not guaranteed.

4. The siteMapped event is only emitted if the site URL is specified in the playbook.

5. Listeners of the contextClosed event are expected to catch their own errors so all listeners are notified.