Antora Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Antora Configuration serves as the foundational orchestration layer for the CircleCI documentation site. It utilizes Antora, a multi-repository static site generator, to aggregate content from various components, apply a unified UI theme, and process AsciiDoc source files into a cohesive technical documentation portal.
The configuration is primarily managed through the antora-playbook.yml file, which defines the relationship between content sources, UI assets, and site-wide metadata. This system enables the separation of content authoring from site presentation, allowing developers to manage documentation versioning and layout independently.
Sources: ARCHITECTURE.md:1-12, TECHNICAL_REFERENCE.md:12-16, README.md:12-18
Site Orchestration and Playbook
The antora-playbook.yml is the central manifest that governs the site's behavior. It specifies the global site title, the production URL, and crawler directives via robots.txt.
The diagram above illustrates how the playbook acts as a central hub for different configuration domains.
Sources: TECHNICAL_REFERENCE.md:18-25, antora-playbook.yml:1-5
Content Source Management
Antora is configured to pull documentation from specific paths within the repository, organized as logical components. These include core guides, reference material, and versioned server administration documentation.
| Component Path | Logical Name | Purpose |
|---|---|---|
docs/root | root | Home and landing pages |
docs/guides | guides | Tutorials and how-to guides |
docs/reference | reference | API and configuration specs |
docs/server-admin-4.x | server-admin | Versioned server docs (4.2 through 4.8) |
docs/contributors | contributors | Guidelines for documentation authors |
Sources: antora-playbook.yml:7-22, TECHNICAL_REFERENCE.md:31-38
Component-Level Configuration
Each component identified in the playbook must contain an antora.yml file. This file provides the metadata required for Antora to index the specific component and its versions.
Component Metadata Attributes
- name: The unique identifier for the component used in cross-references (xrefs).
- version: The version string (e.g.,
4.8). A value of~is used for unversioned content. - start_path: The entry point or landing page for the component.
- nav: A list of AsciiDoc files (usually
nav.adoc) that define the sidebar hierarchy.
Sources: ARCHITECTURE.md:43-52, TECHNICAL_REFERENCE.md:65-73
AsciiDoc and Extension Configuration
The Antora configuration includes a robust set of AsciiDoc attributes and extensions to handle complex technical content like tabs and Mermaid diagrams.
Global Attributes
The playbook defines several version-specific attributes used throughout the documentation to ensure consistency when referencing software versions:
| Attribute | Value | Description |
|---|---|---|
terraformversion | 0.15.4 | Terraform version used in examples |
helmversion | 3.9.2 | Kubernetes Helm version |
serverversion48 | 4.8.4 | Specific patch version for Server 4.8 |
page-toclevels | 6 | Depth of the Table of Contents |
Sources: antora-playbook.yml:33-51, TECHNICAL_REFERENCE.md:52-60
Extension Pipeline
Custom and community extensions are registered within the playbook to modify the document AST (Abstract Syntax Tree) or site-building behavior:
- @asciidoctor/tabs: Enables tabbed content blocks for multi-language or multi-environment examples.
- unlisted-pages-extension.js: Manages pages that should be built but excluded from primary navigation.
- antora-mermaid-extension: Processes Mermaid code blocks into SVG diagrams during the build process.
Sources: antora-playbook.yml:52-70, TECHNICAL_REFERENCE.md:108-115
Build Integration
The Antora build is triggered through Gulp tasks which resolve extension paths and inject environment-specific keys.
The sequence above shows the relationship between the Gulp execution environment and the Antora configuration files.
Sources: gulp.d/tasks/build-site.js:10-25, package.json:10-14
Output Configuration
The build output is directed to the ./build directory. The configuration ensures the directory is cleaned before each build to prevent stale assets from persisting across deployments.
Sources: antora-playbook.yml:26-31, TECHNICAL_REFERENCE.md:43-50
Conclusion
The Antora Configuration in this project provides a modular and scalable approach to managing technical documentation. By centralizing site metadata in the playbook while distributing content-specific logic within component-level files, the system supports complex requirements such as multi-versioned server documentation, custom AsciiDoc extensions, and automated API integration.
Sources: ARCHITECTURE.md:14-23, TECHNICAL_REFERENCE.md:158-165