Install and Quickstart

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 and checked on 2026-10-26. It takes the running example, Pocket Units (a tiny units-conversion library for C# and Python), from an empty directory to a rendered documentation site: install the runtime, install Antora, write the smallest playbook and component that work, build, preview and upgrade. Every command and file below was run with Antora 3.2.1 on Node.js v24.21.0, except where a sentence says otherwise.

What you need

Antora is a Node.js program. A site is produced by three inputs: a playbook file that says what to build, one or more content sources (Git repositories that hold AsciiDoc), and a UI bundle (a ZIP of templates, CSS and JavaScript). Everything else is optional.

  • Node.js. Antora 3.2 requires at least Node.js 20 and its upgrade guide lists Node.js 20, 22 and 24 LTS and Node.js 26 as supported. The quickstart recommends the active long term support release, which is v24 at the start of the 3.2 line.

  • npm, which ships with Node.js.

  • Git for local content sources. Antora reads repositories with its own Git client (isomorphic-git), so a Git command line is not needed to fetch remote repositories, but you need one to create and commit to a local repository.

  • A way to serve static files, only for the preview step.

To check what you have:

node -v
npm -v
git --version

Source: Antora docs: Install and Run Antora Quickstart

The documentation recommends installing Node.js with nvm: nvm install --lts installs the active LTS release on Linux and macOS, and nvm install 24.21.0 is the Windows form. The nvm installation itself was not repeated for this page because Node.js v24.21.0 was already present on the machine used to check it.

Antora also publishes a container image, antora/antora, which lets you run Antora with only Docker or Podman and no local Node.js. It was not pulled or run for this page.

Install Antora

The recommended setup installs Antora inside the project that holds the playbook (a local install) rather than globally. The version of Antora then travels with the playbook, so the playbook always runs on the version it was written for.

mkdir docs-site && cd docs-site
node -e "fs.writeFileSync('package.json', '{}')"
npm i -D -E antora@3.2.1
npx antora -v

Source: Antora docs: Install Antora

Output of the last command:

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

What each part does:

  • node -e "fs.writeFileSync('package.json', '{}')" creates a package.json that contains only an empty object. The documentation prefers this to npm init -y because npm init fills the file with keys that are not needed.

  • -D saves the dependency under devDependencies, and -E stores the exact version instead of a range such as ^3.2.1. Pinning the exact version makes builds reproducible; the lock file package-lock.json pins every transitive package as well.

  • The antora package is a meta package. It installs @antora/cli (the antora command) and @antora/site-generator (the default generator pipeline). The two versions printed by npx antora -v must match.

  • A local install does not put antora on your PATH. Run it as npx antora, which finds the copy in the project or in a parent directory.

The resulting package.json:

{
  "devDependencies": {
    "antora": "3.2.1"
  }
}

Source: Antora docs: Install Antora

Other ways to get the command:

Method Command When to use it

One-off with npx

npx antora -v

Evaluating Antora without installing anything. It works only for Antora by itself, because extensions need to be installed next to it.

Local install (recommended)

npm i -D -E antora@3.2.1

Any real project. Version control package.json and package-lock.json, ignore node_modules.

Global install

npm i -g antora

Puts antora on the PATH. The documentation strongly recommends against it because the Antora version is no longer tied to the playbook.

Container

antora/antora image

No Node.js on the host. See the Docker image documentation for the user ID and cache directory details.

Source: Antora docs: Install Antora

For extensions (search, Collector, Atlas, PDF), install them next to Antora with npm i -D -E and list them under antora.extensions in the playbook. That is covered on the extension pages of this section, not here.

The smallest local site

A single Git repository can hold both the playbook and the content. Antora calls that a mono site. It needs four things in the repository: pages, a navigation file, a component version descriptor (antora.yml) and the playbook. This example describes Pocket Units as a versionless component named ROOT, so its pages publish at the root of the site.

Start by making the directory a Git repository with a first commit. Antora reads content from Git, not from the working directory alone, so a repository without a commit has nothing to read from the branch.

git init -b main
git commit --allow-empty -m init
mkdir -p modules/ROOT/pages

Source: Antora docs: Install and Run Antora Quickstart

Create the start page and one more page:

modules/ROOT/pages/index.adoc
= Pocket Units
:description: A tiny units-conversion library for C# and Python.

Pocket Units converts lengths between metres, feet and inches.

* Start with xref:install.adoc[Install].
* Convert a value with `Converter.Convert(12, LengthUnit.Foot, LengthUnit.Metre)`.
modules/ROOT/pages/install.adoc
= Install

Install the Python package with `pip install pocket-units`.

Source: Antora docs: Install and Run Antora Quickstart

Create the navigation file. The start page of a component version is added automatically as the root of the navigation tree, so only the other pages are listed. An xref with empty link text uses the page title:

modules/ROOT/nav.adoc
* xref:install.adoc[]

Source: Antora docs: Install and Run Antora Quickstart

Create the component version descriptor at the root of the repository. It marks the directory as a content source root and defines the component version:

antora.yml
name: ROOT
version: ~
title: Pocket Units
nav:
- modules/ROOT/nav.adoc

Source: Antora docs: Component Version Descriptor

Here name is the component name used in resource IDs, title is the display name, nav lists the navigation files in order, and version: ~ (YAML for null) declares the component versionless. A versionless component has no version segment in its URLs. The name ROOT is special: its pages are published at the site root, with no component segment either, so the example site exposes install.html rather than pocket-units/install.html. The full set of keys is in Component Version Descriptor.

Finally create the playbook next to antora.yml:

antora-playbook.yml
site:
  title: Pocket Units Docs
  url: http://localhost:8080
content:
  sources:
  - url: .
    branches: HEAD
ui:
  bundle:
    url: https://gitlab.com/antora/antora-ui-default/-/jobs/artifacts/HEAD/raw/build/ui-bundle.zip?job=bundle-stable
    snapshot: true

Source: Antora docs: Install and Run Antora Quickstart

The three top-level keys are the minimum for a useful site:

  • site.title is the name shown in the header and in page titles. site.url is optional, but the 404 page and the sitemap are generated only when it is set, and the sitemap only when it is an absolute URL. Since 3.2 a trailing slash on site.url is removed.

  • content.sources lists the repositories. url: . means the repository that contains the playbook, and branches: HEAD means the branch currently checked out. For a local repository, Antora reads that branch from the working tree, which is why the repository needs at least one commit. Remote repositories and branch patterns are covered in Content Sources.

  • ui.bundle.url points at the UI bundle. It can be a URL or a local path. The URL above downloads the latest build of the Antora default UI from its GitLab job artifacts. snapshot: true tells Antora to download it again whenever fetching is enabled (otherwise a cached copy is used indefinitely), which is the right choice for a bundle published under a moving URL. The playbook keys in full are in Playbook.

No site.start_page is set here: the component is ROOT and versionless, so its start page, index.adoc, becomes the home page of the site. For a component with another name, add start_page: component-name::index.adoc under site; the value uses the same resource ID syntax as an xref.

Add a .gitignore so the output and the installed packages are not committed:

gitignore
/build/
/node_modules/

Source: Antora docs: Install and Run Antora Quickstart

Commit everything. The directory now looks like this:

docs-site
|-- .gitignore
|-- antora-playbook.yml
|-- antora.yml
|-- modules
|   `-- ROOT
|       |-- nav.adoc
|       `-- pages
|           |-- index.adoc
|           `-- install.adoc
|-- package-lock.json
`-- package.json

Since 3.2, the modules directory itself is optional: when it is absent, Antora treats the content source root as an implicit ROOT module. This page keeps the explicit layout, which is the standard one described in Modules and Families.

Build the site

npx antora antora-playbook.yml
ls -1 build/site

Source: Antora docs: Run Antora to Generate Your Site

Output of the second command:

404.html
_
index.html
install.html
sitemap.xml

The first command printed nothing here because it was not run in a terminal. According to the documentation, an interactive terminal gets a completion message with the file URL of the site, and when the environment variable CI is true the site URL is printed instead. Setting IS_TTY to true or false overrides the terminal detection. The _ directory holds the UI bundle files (CSS, JavaScript, fonts and images). 404.html and sitemap.xml exist because site.url is set; with no site.url they are not produced. The pages are at the root because the component is ROOT and versionless.

Useful options for the first builds:

Option Effect

--fetch

Fetch updates for remote repositories and download a snapshot UI bundle again. Without it Antora works offline from its cache, which is a frequent source of confusion when a remote repository changed but the site did not. The same behaviour can be switched on permanently with runtime.fetch: true in the playbook.

--stacktrace

Print the stack trace of an error. Share it when asking for help. Since 3.2 it maps to the runtime.stacktrace key.

--log-failure-level=warn

Exit with code 2 when a message of that level or higher was logged. The default threshold is fatal. The choices are warn, error, fatal and none.

--to-dir=<path>

Write the site somewhere other than build/site. The playbook equivalent is output.dir.

Source: Antora docs: Run Antora to Generate Your Site

Antora reports problems as structured log lines, as JSON when the output is not a terminal. A broken xref in install.adoc (a link to a page that does not exist) produces one error line like this one, shown here with the path shortened:

{"level":"error","name":"asciidoctor","file":{"path":"/home/user/docs-site/modules/ROOT/pages/install.adoc"},"source":{"refname":"main","reftype":"branch"},"msg":"target of xref not found: missing.adoc"}

Source: Antora docs: Log failure level

The output above is trimmed to the keys that matter; a real line also carries a timestamp and the repository URL and worktree path. By default the build still succeeds and exits with code 0, and the site is produced with the broken link left in place. With --log-failure-level=warn the same build exits with code 2 (the exit code changed to 2 in Antora 3.2 when the failure level is exceeded). Use that option in CI so that a broken xref fails the pipeline.

Preview the site

The generated site is plain static files. Serve it through a web server rather than opening file:// pages, because the site URLs are written for a web server (a search index loaded with JavaScript, for example, is not reliably readable from the file system). Any static server will do. Two that were run for this page:

# Python, already installed on most systems
python3 -m http.server 8080 --directory build/site

# Node.js, downloaded on demand by npx
npx -y http-server build/site -p 8080 -c-1

Source: Antora docs: Run Antora to Generate Your Site

Both served the site and returned HTTP 200 for the home page and for install.html. The http-server flag -c-1 disables its caching so a rebuilt page is not stale. The Python server is not documented by Antora; it is shown because it needs no installation. After editing a page, run the Antora command again and reload the browser. The antora command builds once and exits; the official documentation describes no watch mode for content. Live reload exists for the Default UI project, through its own preview task, which is outside this page.

Upgrade from Antora 3.1 to 3.2

Antora 3.2.0 was released on 2026-08-28 and 3.2.1 on 2026-10-01 according to the release notes and the npm registry. The maintainers describe 3.2 as backwards compatible with 3.1.x in practice, so the upgrade is a version change, but check the items below. The last 3.1 release is 3.1.15.

  1. Check Node.js. Antora 3.2 requires at least Node.js 20. Upgrade with nvm install --lts and nvm alias default 24 on Linux and macOS.

  2. Change the version. The upgrade guide recommends giving only major and minor, so that the latest patch release is installed. With the exact pinning used on this page, set the full version instead:

    npm i -D -E antora@3.2.1
npx antora -v

    In a scratch project that had 3.1.15 installed (npx antora -v printed 3.1.15 for both packages before the install), the second command printed:

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

    Source: Antora docs: Upgrade Antora

  3. For a global install, reinstall with npm i -g antora@3.2.

  4. Remove node_modules and package-lock.json for a fresh install if something looks stale (usually unnecessary with npm 8 or later), then rebuild.

  5. Update custom extensions and extension packages (Lunr, Collector, Atlas, PDF) to releases that support Antora 3.2.

Changes in 3.2 that can show up in an existing project:

Change What to check

Exit code 2

A build that exceeds the configured log failure level now exits with code 2, with a hint in the completion message. Scripts that tested for a specific non-zero code need updating.

versionSegment

The URL and output path of a page use the component version’s versionSegment property in place of version, when set. Only affects sites that customise the version segment.

site.url

A trailing slash is stripped, both from the playbook and from a value set by an extension.

Attribute values

An attribute or site key value given in the playbook is parsed as YAML only when it carries an explicit YAML tag, and quotes around the value are no longer stripped. A quoted attribute value may now keep its quotes.

Extension on the CLI

An extension can be switched off from the command line by negating its value, and extensions enabled from the CLI keep the order of those in the playbook.

Worktrees

Linked worktrees and submodules of a local repository work as content sources, HEAD@<worktree> selects a given worktree’s branch, git.fetch_depth limits history fetched from remote repositories, and edit_url accepts a ref placeholder.

UI model

page.file and the resolveResource helper are available in UI templates. resolvePage and resolvePageURL accept no arguments.

Source: Antora docs: What’s new in Antora 3.2

The upgrade shown above was run on an empty project: npm i -D -E antora@3.1.15 followed by npm i -D -E antora@3.2.1, and then the Pocket Units site of this page was built with 3.2.1 without any change to the playbook or content. A real site with extensions and a customised UI was not upgraded here.

Pitfalls

  • Running antora instead of npx antora after a local install fails with a command-not-found error, because a local install does not put the command on the PATH. The documentation suggests alias antora='npx antora'.

  • A local repository without any commit has no HEAD to read, so the build finds no content. Make an initial commit, as shown above.

  • With a remote repository, the cache hides new commits until you pass --fetch or set runtime.fetch: true.

  • Opening build/site/index.html from the file system can break features that load files with JavaScript. Use a static server.

  • The default branches pattern changed in Antora 3 from [master, v*] to [HEAD, v{0..9}*]; for a local repository the current working tree is now used in more cases than before. State branches explicitly, as this page does.

  • The UI bundle URL above is a moving target: it always serves the latest build of the default UI, whose repository publishes no release tags. For a reproducible site, download a bundle once and reference it by a local path or a URL that does not change.

References