升级 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.

If you’re already on Antora 3.0 and ready to upgrade to Antora 3.1, skip the next section and go directly to Upgrade Node.js.

Unresolved include directive in modules/install/pages/upgrade-antora.adoc - include::partial$upgrade-checklist.adoc[]

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.20.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.20.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.1.3",
    "@antora/site-generator": "3.1.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.1 @antora/site-generator@3.1

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.20.0/lib
├── @antora/cli@3.1.3
├── @antora/site-generator@3.1.3
├── npm@8.19.4
└── ...

Learn more

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