Case Study: This Site

Irurueta Docs aggregates the documentation of many independent GitHub repositories into one site. This repository holds no application code. It holds the playbook, one local component named ROOT (the home page and the guides) and a few build helpers. Thirteen Java library repositories and an AI catalog repository each keep their documentation next to their own code, in a docs folder, and the playbook pulls those folders in.

This is the case Antora was designed for: the content stays in the repository of each product, so it is versioned with the code, while presentation and assembly are shared. When a library publishes a release branch, its documentation becomes a new component version on the site without touching this repository.

The complete picture is in the figure. A scheduled or manual GitHub Actions run installs Antora and its extensions, validates the Mermaid diagrams, builds the site from the playbook and publishes the output folder to the gh-pages branch, which GitHub Pages serves at www.irurueta.com.

Figure: the content sources, the UI bundle, the extensions and the deployment of Irurueta Docs.

antora.yml declares the local component. It is deliberately minimal:

Source: Antora docs: Component version descriptor

The component is called ROOT, which Antora publishes at the root of the site, and its version is ~ (YAML null), the versionless form. A versionless component has no version segment in its URLs, so the pages of this repository live at paths such as /documentation-tools/antora/playbook.html. The playbook entry start_page: ROOT::index.adoc makes the home page the landing page. In the scratch build described below, the ROOT home page was written to the site root as index.html.

The local source in the playbook points at this very repository and selects whatever branch is checked out:

Source: Antora docs: Worktrees

There is no start_path, so Antora looks for antora.yml at the repository root. The remote repositories, in contrast, keep their component under docs, which is why each of them declares start_path: docs.

The playbook has 15 content sources: the local one, 13 Java repositories (hermes, irurueta-units, irurueta-statistics, irurueta-sorting, irurueta-algebra, irurueta-numerical, irurueta-geometry, irurueta-geometry-io, irurueta-ar, irurueta-navigation, irurueta-navigation-indoor, irurueta-navigation-inertial and irurueta-navigation-inertial-extra) and ai-catalog. This is an excerpt with the three kinds of entries that occur:

Source: Antora docs: Select branches

These choices are the core of the design:

The playbook does not set git.fetch_depth or any authentication, because all sources are public repositories.

The UI section of the playbook, reproduced here with the analytics, publisher and certification identifiers replaced by placeholders, is:

Source: Antora docs: UI keys

ui-bundle.zip is a custom bundle committed at the repository root. Listing it shows the standard anatomy of a bundle: the folders css, font, helpers, img, js, layouts and partials, with layouts/default.hbs and layouts/404.hbs as the layouts, the stylesheet css/site.css, Roboto web fonts, the helpers and, detag, eq, increment, ne, not, or, relativize and year, and js/vendor/highlight.js for code highlighting. The bundle has no ui.yml. Reading its partials also shows that it sets an SVG favicon in head-icons.hbs, defines a one-line footer in footer-content.hbs, and loads a search script only when the environment variable SITE_SEARCH_PROVIDER is set, which is the contract of the Lunr extension. How bundles are structured and built is explained in UI Bundle and Building a Custom UI.

The extensions are configured at the end of the playbook:

Source: Antora docs: AsciiDoc extensions in the playbook

Two extensions are active and they work in opposite places:

experimental: '' sets the AsciiDoc experimental attribute, which enables the keyboard, button and menu macros. @antora/lunr-extension is listed in package.json and installed by the workflows, but its require line is commented out in the playbook, so the site has no built-in search. Search and its alternatives are covered in Site Search.

A Mermaid diagram that does not parse is not reported by the Antora build, because the diagram is only parsed in the browser. That is why the repository carries scripts/validate-mermaid.mjs: it runs every block through the Mermaid parser and fails the workflow before the build when one is broken. Locally, install the validator dependencies once and run it:

Source: Antora Mermaid extension

This command was not executed here against the whole site, which has thousands of diagrams; the script was run on the Documentation Tools pages while writing them.

The workflow publish.yml runs every day at 03:00 UTC. manual_publish.yml has the same steps and runs on workflow_dispatch, for a build on demand. The file below is publish.yml verbatim; the step names are in Spanish.

Source: Antora docs: Publish to GitHub Pages

The workflow was not executed here, because it needs the GitHub repository and its token; the equivalent local steps (install, build) were run in a scratch directory. Points worth noting:

The release flow, from a library repository to the published site, is:

Figure: how a release branch of a library repository becomes a version of the published site.

The commands to build this site on a workstation, with Node.js installed, are the ones documented in the repository’s CLAUDE.md:

Source: Antora docs: Antora CLI

The first build clones the remote repositories into the Antora cache; --fetch updates them on later runs. The output goes to build/site, which is ignored by git. Only a build that finishes without unresolved xref or AsciiDoc errors is meaningful, and figures need extra checking: this repository’s CLAUDE.md documents that an image macro split over two lines is rendered as plain text without any build error, so block macros are kept on one line and checked with grep. These commands were not run against the whole site here, because that would clone all 14 remote repositories.