Antora Extensions
Relevant source files
The following files were used as context for generating this wiki page:
Antora Extensions are modular JavaScript components used to enhance or modify the core functionality of the Antora documentation site generator. Within the CircleCI Docs project, these extensions handle specialized tasks such as content exportation for external search indexing, page-level metadata enrichment, and the management of unlisted content.
These extensions interact directly with Antora's lifecycle, allowing the build process to manipulate the content catalog, modify the Document Object Model (DOM) of generated pages, or integrate with third-party services like Algolia. They are registered within the antora-playbook.yml and are executed during the site generation process.
Sources: ARCHITECTURE.md:20-22, ARCHITECTURE.md:111-125, TECHNICAL_REFERENCE.md:120-137
Extension Architecture and Registration
Extensions are implemented as JavaScript modules that export a register function. This function receives a registry object, which provides hooks into various stages of the Antora build process. The registration occurs in the antora-playbook.yml file under the antora.extensions key.
The diagram above illustrates how extensions registered in the playbook hook into different parts of the Antora engine.
Registration Configuration
In the project's configuration, extensions can be local files or external npm packages.
| Extension Name | Source Path / Package | Purpose |
|---|---|---|
| Unlisted Pages | ./extensions/unlisted-pages-extension.js | Manages pages excluded from the main navigation. |
| Mermaid | @sntke/antora-mermaid-extension | Renders Mermaid diagrams in AsciiDoc content. |
| Content Export | ./extensions/export-content-extension.js | Exports site content for external indexing. |
| Page Metadata | ./extensions/page-metadata-extension.js | Adds commit history and metadata to pages. |
Sources: antora-playbook.yml:68-87, TECHNICAL_REFERENCE.md:120-128, ARCHITECTURE.md:46-51
Core Extension Mechanisms
The project utilizes three primary custom extensions to handle documentation-specific requirements that fall outside of Antora's default behavior.
Unlisted Pages Extension
This extension allows certain pages to be included in the build output even if they are not explicitly linked in a nav.adoc file. This is useful for "hidden" documentation or feature-specific landing pages.
- Logic: It checks the
allowedUnlistedPagesconfiguration provided in the playbook. - Action: It intercepts the content catalog and prevents Antora from throwing errors or omitting pages that lack a navigation entry.
Sources: antora-playbook.yml:69-72, extensions/unlisted-pages-extension.js
Page Metadata Extension
The Page Metadata extension enriches the documentation with environmental and version control data.
- Logic: It identifies the latest Git commit for a given file and calculates the "last updated" date.
- Action: It injects this metadata into the page's attributes, which can then be rendered in the UI (e.g., "Last updated on..."). It also handles badges for content status such as "Beta" or "Preview".
Sources: ARCHITECTURE.md:118-121, extensions/page-metadata-extension.js
Content Export Extension
This extension facilitates the integration between the static site and the search engine.
- Logic: It traverses the generated content pages after they have been processed.
- Action: It extracts relevant text, headings, and metadata to generate a JSON payload suitable for Algolia search indexing.
Sources: ARCHITECTURE.md:114-116, TECHNICAL_REFERENCE.md:168-175, extensions/export-content-extension.js
Data Flow in Extension Execution
Extensions typically follow a sequence where they listen for specific Antora events, modify the internal data structures, and then pass control back to the generator.
The sequence diagram shows the interaction between the Antora core and a custom extension during the content classification phase.
Sources: TECHNICAL_REFERENCE.md:130-137, DEVELOPMENT.md:133-143
Summary
Antora Extensions serve as the primary customization layer for the CircleCI documentation pipeline. By leveraging these extensions, the project automates metadata generation, enables advanced diagram rendering via Mermaid, and maintains a bridge to external search platforms. Developers can add new functionality by implementing the register API and adding the script to the extensions/ directory and the main playbook configuration.