Antora Overview

This content was generated with the assistance of AI and should be verified against the official documentation of each tool before being relied on in production.

This section’s bibliography lists the reference material consulted while preparing these pages.

This page was written against Antora 3.2.1 (npm packages antora, @antora/cli and @antora/site-generator, published 2026-10-01) and checked on 2026-10-26. Antora needs Node.js 20 or newer. It is the tool that builds this very site, so the explanations below use a small running example, Pocket Units, a units-conversion library with C# and Python sources, documented as one Antora component with two versions.

What Antora is

Antora is a static site generator for technical documentation. Authors write pages in AsciiDoc, keep them in a standard directory layout inside one or more git repositories, and describe in a single YAML file, the playbook, where the content and the user interface (UI) come from. Antora reads the content, converts it and writes a plain HTML site that can be served from any web server or static host. The project positions itself around "docs as code": content under version control, content separated from presentation, automation and reuse.

Three ideas distinguish Antora from generators that start from a single folder of Markdown files:

Multiple repositories, one site. A playbook lists any number of content sources. Each source can be a local directory or a remote git repository, so product teams keep the documentation next to their code and the site aggregates it. This site pulls the documentation of a dozen other repositories this way.
Versions come from git. Antora reads branches and tags, and every branch or tag that carries a component version descriptor becomes a version of a documentation component. Several versions can be published side by side.
The UI is separate. The look of the site comes from a UI bundle, a ZIP of Handlebars templates, CSS, JavaScript and images, that is referenced from the playbook and can be replaced without touching the content.

Antora, its documentation site and the default UI are licensed under the Mozilla Public License 2.0 (MPL-2.0).

AsciiDoc and Asciidoctor.js

Antora does not invent a markup language. Pages are written in AsciiDoc, a plain-text markup with built-in support for includes, cross-references, attributes, tables, admonitions, callouts and extension points. The Asciidoctor project provides the processor that turns AsciiDoc into HTML; Antora uses Asciidoctor.js, the JavaScript build of that processor, which is why Antora runs on Node.js and needs no Ruby. The Antora site notes that Antora’s core developers help lead the Asciidoctor organization.

Antora configures Asciidoctor.js for you and adds a few things on top of plain AsciiDoc:

Resource IDs. Cross-references, includes and images use identifiers of the form version@component:module:family$path, so a page can link to another module, component or version, not just to a neighbouring file. They are covered on Resource IDs and Xrefs.
Families and modules. Every file belongs to a module and a family such as pages, partials, examples, images or attachments; see Modules and Families.
Attributes. Site, component and page attributes can be set in the playbook and in the component descriptor, see AsciiDoc Attributes and Extensions.
Asciidoctor extensions. The playbook key asciidoc.extensions registers Asciidoctor.js extensions. This site uses it for Mermaid diagrams and MathJax formulas, as described in the repository’s CLAUDE.md.

A page in the Pocket Units component looks like any AsciiDoc document. The title, a description attribute and a cross-reference to another page of the same module are enough to see the idea:

= Getting Started
:description: Install Pocket Units and run your first conversion.

Add the package, then read xref:guides:converting-lengths.adoc[Converting lengths].

Source: Antora docs: Pages

How Antora works

Antora is a pipeline. Its build happens in one process: it reads the playbook, collects every file from the repositories, builds an in-memory catalog and writes the result to disk. The official page "How Antora Works" splits that run into steps; they group naturally into six stages.

flowchart LR A["Playbook
antora-playbook.yml"] --> B["Aggregate
clone or read repositories,
find antora.yml"] B --> C["Classify
assign module, family
and output paths"] C --> D["Convert
Asciidoctor.js turns AsciiDoc
into embeddable HTML"] D --> E["Navigation
build the nav model
from nav files"] E --> F["Compose
wrap pages in UI
templates"] G["UI bundle
ui-bundle.zip"] --> F F --> H["Publish
write site to output dir"] H --> I["build/site"]

Aggregate. Antora builds the playbook from the file, the command line and the environment, then loads the content sources. Remote repositories are cloned or fetched into a cache; local ones are read in place. For every selected branch or tag it looks for an antora.yml file in the source root, which marks the start of a component version, and turns each file below it into a virtual file object assigned to that component version.
Classify. Antora computes the module, the family and the relative path of each file, and from them the output path and the publish URL. The files are organized into a content catalog together with the component versions and their start pages.
Convert. Asciidoctor.js converts every page to embeddable HTML (the page body without the surrounding template). Cross-references are resolved against the catalog at this point, so a link to a page that does not exist is reported here.
Navigation. Navigation files registered in each antora.yml are converted into a navigation model that the UI shows as the menu of the component version.
Compose with the UI. The UI bundle is fetched from the URL or path in the playbook, cached, unpacked and classified with the help of its ui.yml descriptor. Each page is then wrapped in a UI template and receives the page HTML, the site metadata and the navigation model. The UI is loaded concurrently with the content, so its exact position in the sequence can vary.
Publish. Antora produces a sitemap when site.url is set and writes the pages, the UI files and the other resources to the output location, by default a directory but also an archive or other providers.

A run with extensions can hook into these stages through generator events such as contentAggregated, navigationBuilt or beforePublish; that is the subject of Antora Extensions.

Running the pipeline on Pocket Units

The scratch project used for this section has a playbook that aggregates two branches of the Pocket Units repository (v1.0 and v2.0) and a second repository, shared, that holds a style guide:

site:
  title: Pocket Units Docs
  url: http://localhost:5252
  start_page: pocket-units::index.adoc
content:
  sources:
  - url: ./src/pocket-units
    branches: [v1.0, v2.0]
  - url: ./src/shared
    branches: main
ui:
  bundle:
    url: ./ui-bundle.zip
    snapshot: true
output:
  dir: build/site

Source: https://docs.antora.org/antora/latest/playbook/

Each source root carries the component version descriptor. For the v2.0 branch it is:

name: pocket-units
title: Pocket Units
version: '2.0'
nav:
- modules/ROOT/nav.adoc
- modules/guides/nav.adoc
asciidoc:
  attributes:
    product-name: Pocket Units

Source: https://docs.antora.org/antora/latest/component-version-descriptor/

Running the generator on the scratch project with Antora 3.2.1 printed the version and then produced the following files, one version of the component per branch and one versionless component for the shared content:

npx antora --version
npx antora --fetch antora-playbook.yml

@antora/cli: 3.2.1
@antora/site-generator: 3.2.1

build/site/index.html
build/site/404.html
build/site/shared/style-guide.html
build/site/pocket-units/1.0/index.html
build/site/pocket-units/1.0/getting-started.html
build/site/pocket-units/2.0/index.html
build/site/pocket-units/2.0/getting-started.html

Source: https://docs.antora.org/antora/latest/cli/

The listing of generated files is abridged: the real build also writes the changelog and guide pages of both versions, the sitemaps and the UI files. The playbook shown above uses a placeholder UI path; the scratch build used a locally built copy of the Antora Default UI.

Who uses Antora

The official Antora site does not publish a list of adopters or a showcase, so this page does not make claims about who else uses it. What can be said from sources checked for this page is that Antora builds its own documentation site (hosted on Netlify), that it is developed in the open on GitLab where the project reports the usage numbers below, and that this site, Irurueta Docs, is an Antora site that aggregates the documentation of many other repositories. The comparison page of this section collects the project metrics that were fetched on 2026-10-26.

Metric (2026-10-26) Value

Metric (2026-10-26)	Value
Latest release	3.2.1 (2026-10-01); 3.2.0 was published on 2026-08-29 and 3.1.15 is the last 3.1 release
GitLab project `antora/antora`	599 stars, 395 forks
npm weekly downloads (2026-10-16 to 2026-10-22)	`@antora/cli` 23,818; `antora` 7,580
Stack Overflow tag `antora`	31 questions

Latest release

3.2.1 (2026-10-01); 3.2.0 was published on 2026-08-29 and 3.1.15 is the last 3.1 release

GitLab project antora/antora

599 stars, 395 forks

npm weekly downloads (2026-10-16 to 2026-10-22)

@antora/cli 23,818; antora 7,580

Stack Overflow tag antora

31 questions

Source: npm: antora

When to choose Antora

Antora fits best when documentation is spread over several repositories or must exist in several versions at once.

Choose Antora when	Look elsewhere when
Several repositories or teams contribute to one site and each keeps its docs next to its code.	You document a single project in one repository with no versions; a simpler generator needs less setup.
You publish several released versions side by side and want them taken from git branches or tags.	Your authors work in Markdown and cannot move to AsciiDoc.
You need strong cross-references, includes and reusable partials across modules and components.	You want a ready-made, single-command site with many bundled themes and plugins, without assembling a UI bundle.
You want to own the look of the site through a UI bundle that can be shared by many sites.	You need the generator to be built on React components or Python tooling; Antora’s extension model is JavaScript on Node.js.

Choose Antora when

Look elsewhere when

Several repositories or teams contribute to one site and each keeps its docs next to its code.

You document a single project in one repository with no versions; a simpler generator needs less setup.

You publish several released versions side by side and want them taken from git branches or tags.

Your authors work in Markdown and cannot move to AsciiDoc.

You need strong cross-references, includes and reusable partials across modules and components.

You want a ready-made, single-command site with many bundled themes and plugins, without assembling a UI bundle.

You want to own the look of the site through a UI bundle that can be shared by many sites.

You need the generator to be built on React components or Python tooling; Antora’s extension model is JavaScript on Node.js.

Trade-offs to keep in mind: the learning curve is steeper than for a single-folder generator, because there are new concepts (playbook, component version descriptor, modules, families, UI bundle), and a UI bundle must exist before the first build. The Default UI is distributed as a CI job artifact rather than as tagged releases. The extensions for search (@antora/lunr-extension, 1.0.0-alpha.13) and for cross-run references (@antora/atlas-extension, 1.0.0-alpha.6) are still alpha releases at the check date. The sibling pages of this section compare Antora with Docusaurus, Zensical and DocFX.

Map of the Antora pages

Page What it covers

Page	What it covers
Install and Quickstart	Node.js setup, installing Antora, a minimal playbook and component, local preview and upgrading from 3.1 to 3.2.
Playbook	Every playbook key and the precedence of the command line, environment variables and the file.
Content Sources	Repositories, branches, tags, globs, worktrees, start paths, edit URLs, shallow fetches, submodules.
Component Version Descriptor	The keys of `antora.yml` and versionless components.
Versioning and Prerelease	How branches and tags become versions, prereleases, sorting and URL segments.
Modules and Families	The standard directory layout and how it maps to output URLs.
Resource IDs and Xrefs	The resource ID syntax and cross-references between pages, modules, components and versions.
Navigation	Navigation files, their registration and composition.
Partials, Examples and Attachments	Reusing content with includes and offering downloads.
AsciiDoc Attributes and Extensions	Attribute levels and Asciidoctor extensions such as Mermaid and MathJax.
Antora Extensions	The extension API, generator events and writing an extension.
Site Search	The Lunr extension, its UI contract and options.

Install and Quickstart

Node.js setup, installing Antora, a minimal playbook and component, local preview and upgrading from 3.1 to 3.2.

Playbook

Every playbook key and the precedence of the command line, environment variables and the file.

Content Sources

Repositories, branches, tags, globs, worktrees, start paths, edit URLs, shallow fetches, submodules.

Component Version Descriptor

The keys of antora.yml and versionless components.

Versioning and Prerelease

How branches and tags become versions, prereleases, sorting and URL segments.

Modules and Families

The standard directory layout and how it maps to output URLs.

Resource IDs and Xrefs

The resource ID syntax and cross-references between pages, modules, components and versions.

Navigation

Navigation files, their registration and composition.

Partials, Examples and Attachments

Reusing content with includes and offering downloads.

AsciiDoc Attributes and Extensions

Attribute levels and Asciidoctor extensions such as Mermaid and MathJax.

Antora Extensions

The extension API, generator events and writing an extension.

Site Search

The Lunr extension, its UI contract and options.

The UI bundle, the supplemental UI and the Default UI project are described on their own pages in the documentation-tools/antora/ui folder of this section, and the remaining pages cover publishing, private repositories, Docker and migrations.