The Spring Boot documentation system utilizes Antora to aggregate and publish its multi-module reference documentation. This system replaces traditional monolithic Asciidoctor builds with a component-based architecture that pulls content from various source locations, applies specialized extensions for cross-referencing and zip collection, and manages a local Node.js environment for build reproducibility.
The AntoraConventions class in buildSrc orchestrates the integration between Gradle and the Antora CLI. It applies the AntoraPlugin and GenerateAntoraYmlPlugin to documentation projects, setting up a standardized environment for generating the site.
Diagram: Antora Task Orchestration
Key responsibilities of AntoraConventions:
resolveBom configuration to pull the resolvedBom artifact from :platform:spring-boot-dependencies buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java83-86NodeExtension to ensure the project uses a local Node installation managed by the com.github.node-gradle.node plugin buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java100-101GenerateAntoraPlaybook task which uses antora-playbook-template.yml to create a transient playbook for the current build buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java89-91Sources: buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java78-123 buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-playbook-template.yml
A critical part of the documentation is the dynamic injection of version numbers and URLs. The AntoraAsciidocAttributes class extracts metadata from the project's BOM (Bill of Materials) and build properties to populate Asciidoctor attributes.
Diagram: Attribute Extraction Flow
build-type as an identifier (e.g., opensource or commercial) based on the BuildType resolved from project properties buildSrc/src/main/java/org/springframework/boot/build/antora/AntoraAsciidocAttributes.java134-136main, 3.2.x, or v3.2.1) for source code links using the project version and the latestVersion flag buildSrc/src/main/java/org/springframework/boot/build/antora/AntoraAsciidocAttributes.java143-154version-<linkRootName> attribute using the version defined in the Library object buildSrc/src/main/java/org/springframework/boot/build/antora/AntoraAsciidocAttributes.java157-161antora-asciidoc-attributes.properties and appends version-specific paths for Spring Data and other dependencies buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-asciidoc-attributes.properties8-84Sources: buildSrc/src/main/java/org/springframework/boot/build/antora/AntoraAsciidocAttributes.java121-132 buildSrc/src/main/resources/org/springframework/boot/build/antora/antora-asciidoc-attributes.properties1-95
The Antora runtime is managed via a locked package-lock.json file in the root antora/ directory. This ensures that all contributors and CI runners use identical versions of the Antora CLI and its extensions.
The environment includes several specialized extensions:
@antora/atlas-extension: Handles advanced site mapping and navigation antora/package.json8@springio/antora-extensions: A suite of Spring-specific Antora enhancements, including the root-component-extension antora/package.json9@springio/antora-xref-extension: Provides enhanced cross-referencing capabilities across different Antora components antora/package.json10@springio/antora-zip-contents-collector-extension: Allows Antora to pull documentation source directly from ZIP artifacts produced by other Gradle tasks antora/package.json11@asciidoctor/tabs: Adds support for tabbed code blocks (e.g., switching between Java and Kotlin) antora/package.json12The package-lock.json file pins @antora/cli and @antora/site-generator to version 3.2.0-rc.2 antora/package-lock.json9-10 The AntoraConventions task antoraNpmInstall executes npm ci --silent to install these dependencies into a project-local node_modules folder, omitting optional dependencies buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java142-147
Sources: antora/package.json5-14 antora/package-lock.json5-17 buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java139-147
The documentation system is deeply integrated with the BomExtension. Metadata defined in the BOM is used to generate Javadoc links and version properties in the reference guide.
| Class Entity | Role in Documentation |
|---|---|
Library | Represents a group of modules (e.g., "Spring Framework") with a linkRootName used for attribute keys and version property generation buildSrc/src/main/java/org/springframework/boot/build/bom/Library.java60-85 |
BomExtension | Holds the master list of libraries and their versions, providing the DSL for documentation-relevant metadata buildSrc/src/main/java/org/springframework/boot/build/bom/BomExtension.java80-81 |
ResolvedBom | Provides the actual resolved versions of dependencies after conflict resolution, used to populate attributes for specific managed artifacts buildSrc/src/main/java/org/springframework/boot/build/bom/ResolvedBom.java37-41 |
CheckLinks | A task that verifies all external documentation links defined in the BOM (e.g., releaseNotes links) are still valid buildSrc/src/main/java/org/springframework/boot/build/bom/BomPlugin.java71 |
Sources: buildSrc/src/main/java/org/springframework/boot/build/bom/Library.java104-121 buildSrc/src/main/java/org/springframework/boot/build/bom/BomExtension.java113-127
To prevent broken links in the reference manual, the build includes a CheckJavadocMacros task. This task scans the Antora source files for custom Javadoc macros and verifies that the referenced classes exist on the classpath.
ANTORA_SOURCE_DIR (src/docs/antora) buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java71javadocMacros configuration that extends from the main runtime classpath of the documentation project to ensure it has access to all project dependencies buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java113-120Sources: buildSrc/src/main/java/org/springframework/boot/build/AntoraConventions.java102-122