Most important of all, a huge thank you! to all the folks who helped make Antora even better.

When Antora launched, nodegit was the only git client for JavaScript that provided the features Antora required for interfacing with git repositories (clone, fetch, resolve refs, walk trees, read blobs). Despite being a comprehensive git client, nodegit has proven to be tremendously difficult for users to install. This difficulty stems from its coupling to native system libraries for compilation, bundling of native libraries, limited portability across platforms and Node versions, misbehaving post-install scripts, reliance on an SSH agent for authentication, and lack of interest in addressing portability concerns.

Since then, a full-fledged alternative has emerged. Our friend William Hilton stepped up to create isomorphic-git, a pure JavaScript git client (fun fact, it also runs in a browser). In Antora 2.0, we’ve completely replaced nodegit with isomorphic-git.

Switching Antora to isomorphic-git not only guarantees a hassle-free installation, but drastically reduces installation time and size as well. This improvement is a result of Antora’s dependencies no longer relying on native system libraries. And it means Antora now works on all platforms and supported Node versions.

isomorphic-git also allowed us to expand our test coverage and therefore improve Antora’s stability. isomorphic-git drives all of the git tests in the test suite. And those tests now use proper remote clone and fetch operations to test remote repositories.

All-in-all, the switch from nodegit to isomorphic-git has been very positive, a huge step forward for Antora, and the main reason for the major version jump to Antora 2.0.

Replacing nodegit with isomorphic-git brought with it a breaking change in how Antora handles private repository authentication. Private repository authentication is now performed using HTTP Basic authentication over HTTPS instead of public/private key authentication over SSH using an SSH agent.

This change makes it easier to manage authentication because Antora no longer requires running an SSH agent. Instead, authentication credentials can be managed using the git credential store mechanism or a custom credential manager provided by the user.

If you use private repositories, you’ll need to add authentication credentials for each git host (or individual repository) to the default or a custom git credentials store before running Antora 2.0. To learn what types of credentials Antora can use for authentication and how to add your credentials to the default credentials store, refer to the Private repository authentication documentation.

Here’s a quick summary of where those credentials can be stored:

The documentation has examples showing how to specify a custom git credential store using each of the methods listed above. If none of these options meet your requirements, the documentation also shows how to implement your own credential manager plugin.

Finally, Antora transparently converts git SSH URLs in your playbook to HTTPS URLs so you don’t have to modify your playbook file when upgrading to Antora 2.0. If this automatic translation doesn’t work, meaning a git repository is not available at the equivalent HTTPS URL, then you’ll need to update your playbook file to use the correct HTTPS URL.

Antora 2.0 ships with Asciidoctor.js 1.5.9 thanks to the hard work by Guillaume Grossetie. This release of Asciidoctor.js brings you the latest Asciidoctor features, updates the Asciidoctor.js API, fixes conflicts with libraries, and offers several nice enhancements to the AsciiDoc syntax. Here are some of the highlights:

See the release notes for Asciidoctor and Asciidoctor.js to find complete details.

Most important of all, a huge thank you! to all the folks who helped make Antora even better.

The raw install size of Antora drops from 154MB down to 43MB. The Docker image on DockerHub dropped from 60 MB to 29 MB. It took 11 seconds to install Antora 1.1.1 from cache. It only takes 3 seconds to install Antora 2.0.0 from cache.

You may need to make some of the following changes to your documentation system before using Antora 2.0.

If you answered No to all of the above questions, then you’re ready to upgrade to Antora 2.0 now! See Upgrade Antora for instructions.

Antora 1.1 will enter maintenance on March 25, 2019. See the release schedule for details.