Upgrade Antora

Upgrade checklist

If you’re upgrading from Antora 1.1, you may need to make some of the following changes to your documentation system before using Antora 2.1.

Does Antora access private repositories in order to build your site?: If yes, you get to say goodbye to your SSH agent and set up your authentication credentials for each private repository URL in a git credential store. Refer to the Private repository authentication documentation for setup options and instructions.
Does Antora access git repositories using the git: protocol or static HTTP (such as a host using cgit)?: Unfortunately, Antora can no longer connect to repositories that use these connection methods. You’ll need to either clone the repositories to a local folder and point Antora at those locations or you’ll need to set up a proxy server that serves the repositories over smart HTTP (as do all major git hosts).
Is your Antora playbook file written in CSON?: If yes, you’ll need to migrate it to YAML, JSON, or TOML before running Antora 2.1.

If you answered No to all of the above questions, then you’re ready to upgrade to Antora 2.1 now!

On this page, you’ll learn:

How to upgrade Node. (optional)
How to upgrade Antora globally.
How to upgrade the Antora CLI and default site generator individually.

Upgrade Node (optional)

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

To check which Node version you have installed, open a terminal and type:

$ node --version

If you need to upgrade to the latest Node LTS version, type:

Linux and macOS

$ nvm install --lts

Windows

$ nvm install 10.16.3

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

Linux and macOS

$ nvm alias default 10

Windows

$ nvm alias default 10.16.3

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

Upgrade Antora globally

If you installed the Antora CLI and default site generator globally, you can upgrade them at the same time.

In a terminal, type:

$ npm install -g @antora/cli@2.1 @antora/site-generator-default@2.1

npm will automatically install the latest version of Antora.

Do I have Antora installed globally?

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

$ npm ls -g --depth=0

If you installed the Antora CLI and site generator globally, you’ll see them listed in the terminal output alongside their version numbers (where .x represents the latest patch number).

List of globally installed Node packages

/home/user/.nvm/versions/node/v10.16.3/lib
├── @antora/cli@2.1.x
├── @antora/site-generator-default@2.1.x
├── npm@6.11.2
└── ...

If you only see the CLI (@antora/cli) listed, then you installed the site generator in a specific local project directory. In this case, you’ll need to upgrade the Antora CLI and site generator as described in the following section.

Upgrade the Antora CLI and site generator separately

If you didn’t install a previous version of Antora site generator globally, you’ll need to upgrade the Antora CLI and default site generator separately.

Upgrade the CLI globally by typing:

$ npm install -g @antora/cli@2.1

Change to your local project directory. This is typically where your Antora playbook file, antora-playbook.yml, is stored.
Open the package.json file.
Change the version number of the site generator. We recommend specifying a partial version number (major.minor) so that you receive the latest patch update.
```
{
  "dependencies": {
    "@antora/site-generator-default": "2.1"
  }
}
```
Save the file.
Upgrade the site generator by running the npm install command.
```
$ npm install
```

If you’re using yarn instead of npm, run the yarn command after updating package.json. It may be necessary to pass the --force flag to force an update.

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

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