Upgrade Antora

On this page, you’ll learn:

How to upgrade Node.js.
How to upgrade Antora globally.
How to upgrade the Antora CLI and site generator individually.

Upgrade checklist

Before you upgrade from Antora 2.3 to Antora 3.0, you may need to make some of the following changes to your documentation system.

Are you using an active LTS version of Node.js?: We recommend upgrading to the latest active long term support (LTS) release of Node. Antora 3 officially supports Node.js 16 LTS and is tested on Node.js 18 LTS. Antora 3 doesn’t support Node.js versions that have reached end of life (EOL). See Upgrade Node.js for instructions.
Have you updated your AsciiDoc syntax and Asciidoctor extensions to comply with the newest patch release of Asciidoctor.js 2.2?: Antora 3 dropped support for Asciidoctor.js 1.5.9 (which provides Asciidoctor 1.5.8) and now depends on the latest patch version of Asciidoctor.js 2.2 (which provides Asciidoctor 2.0.x). Asciidoctor 2 introduces a few substantive changes to existing features that may impact your documentation source content or UI. See Asciidoctor Upgrade Notes to learn about the affected features and the suggested actions you should take before upgrading to Antora 3.
Are you linking to attachment files?: Using the AsciiDoc link macro (link:[]) and {attachmentsdir} attribute reference in the target value to reference an attachment has been deprecated in Antora 3. Replace the link macro with the xref macro and use the attachment’s resource ID to reference it. See Attachments and Attachment Xrefs in Navigation Files to learn about the attachment$ family coordinate and for usage examples.
Are any of your component versions unversioned?: We’ve deprecated the use of the value master, when assigned to the version key, to identify an unversioned component. In Antora 3, assign the tilde (~) to the version key in a component version’s antora.yml file to specify it as unversioned. See Define a Component with No Version to learn more.
Make sure you’re using file extensions when cross referencing pages or assigning page-aliases values.: If the .adoc file extension was missing from the resource ID in an xref macro or the value assigned to a page-aliases attribute, Antora 2 would automatically add .adoc to the resource ID at runtime. This fallback mechanism has been deprecated because the xref macro can now reference other non-AsciiDoc resources. Review the resource IDs in your xrefs and page-aliases attributes to ensure the .adoc extension is specified.
Are you depending on the default branches pattern in your playbook?: The previous default branches pattern, [master, v*], has been deprecated and replaced with [HEAD, v{0..9}*]. It’s unlikely this will cause a change when using remote repositories. For local repositories, it may result in the worktree being used in cases it wasn’t previously.
Do you use the antora-lunr add-on to integrate Lunr into your site?: The antora-lunr add-on was designed for Antora 2 and is a community-maintained project. In Antora 3, antora-lunr has been replaced by the Antora Lunr extension (package: @antora/lunr-extension), which is an official Antora project. This extension uses the new extension facility in Antora 3 to integrate Lunr into your site without having to resort to using a custom site generator. We encourage you to migrate from antora-lunr to the Antora Lunr Extension when upgrading to Antora 3.
Do you use or maintain a custom site generator?: In Antora 3, the site generator must declare the @antora/logger package as a dependency. The CLI resolves the logger relative to the site generator. If it cannot find it there, it will fall back to the logger provided by the CLI. This may result in Antora configuring the wrong logger, which will result in the user to see a warning about the logger not being configured.

Also note that the recommended signature of the generateSite function has changed. The function now accepts a single parameter, the playbook. The old signature is still supported, but using it will result in the playbook being built a second time.

The site generator should also depend on the @antora/file-publisher package instead of @antora/site-publisher, though technically this isn’t required.
Do you use a custom git credential manager?: Isomorphic-git no longer includes the cores (plugin) API, so the call git.cores.create('antora').set('credentialManager', customCredentialManager) is going to fail. Antora still honors the cores API, but the call to register the credential manager is now responsible for creating it (since it runs before Antora loads). Refer to Configure a custom credential manager for the latest instructions.

Upgrade Node.js (optional)

You can use any active LTS or maintenance LTS version of Node.js with Antora, but we recommend using the most recent active LTS version so that you benefit from the latest performance and security enhancements. The Node.js release schedule shows the active Node.js LTS versions.

To check which Node.js version you have installed, open a terminal and run:

$ node --version

If you need to upgrade to the active Node.js LTS version, run:

Linux and macOS

$ nvm install --lts

Windows

$ nvm install 16.16.0

Next, to set the latest version of Node.js as the default for any new terminal, run:

Linux and macOS

$ nvm alias default 16

Windows

$ nvm alias default 16.16.0

Now you’re ready to upgrade to the latest version of Antora.

Upgrade Antora locally

If you have installed Antora locally, you will use package.json to manage the version. This file tracks which version of Antora you currently have installed. You can use the file to specify a different version. The npm i command will consult this file to determine which packages and which versions of those packages to install.

Switch to your playbook project where your Antora playbook file (e.g., antora-playbook.yml) is stored.
Open the package.json file.
Change the version number of the CLI and site generator.
```
{
  "devDependencies": {
    "@antora/cli": "3.0.3",
    "@antora/site-generator": "3.0.3"
  }
}
```
Unless you’re installing a prerelease, we recommend specifying only the major.minor version number so you receive the latest patch update.
Save the file.
(Optional) Remove the node_modules folder and package-lock.json file. Although removing the node_modules folder is not always required, doing so ensures you get a fresh installation. If you’re using at least npm 8, this step is usually unnecessary.
Upgrade the site generator by running the npm i command.
```
$ npm i
```

You’ve now upgraded to the latest version of Antora.

As an alternative to removing the node_modules folder, you can use npm upgrade, which closely mimics a fresh installation.

Upgrade Antora globally

If you installed the Antora CLI and site generator globally, you can upgrade them by reinstalling the packages:

In a terminal, run:

$ npm i -g @antora/cli@3.0 @antora/site-generator@3.0

The npm i command will remove any existing packages with the same name and install them anew.

Do I have Antora installed globally?

To list your globally installed Node.js packages, type the following command in your terminal:

$ npm ls -g --depth=0

If you’ve installed the Antora CLI and site generator globally, you’ll see them listed in the terminal output alongside their version numbers.

List of globally installed Node.js packages

/home/user/.nvm/versions/node/v16.16.0/lib
├── @antora/cli@3.0.3
├── @antora/site-generator@3.0.3
├── npm@8.2.0
└── ...

Learn more

Review What’s New in Antora for the latest features and potential breaking changes.