What’s New in Antora

Learn about what’s new in the 2.0 release series of Antora.

Antora 2.0.0

Release date: 2018.12.25 | Milestone (closed issues): v2.0.x

The Antora 2.0.0 release streamlines the installation process, improves platform and library compatibility, provides a simpler and pluggable authentication mechanism for private repositories, and delivers the latest Asciidoctor capabilities.

If you need a quick overview of the breaking changes, jump to the upgrade checklist.

Hassle-free installation thanks to isomorphic-git

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.

Goodbye SSH. Hello git credentials.

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:

  • $HOME/.git-credentials by default

  • --git-credentials-path CLI option — override location of git credential store

  • GIT_CREDENTIALS_PATH environment variable — override location of git credential store

  • git.credentials key in Antora playbook — override path or contents of git credential store

  • GIT_CREDENTIALS environment variable — override contents of git credential store

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.

All the latest Asciidoctor features

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:

AsciiDoc
  • Nest ordered and unordered lists to an arbitrary depth.

  • Autonumber callout markers using the <.> syntax.

  • Create an xref with automatic text to a list item or table cell.

  • Attribute references in the attribute list of an include directive are replaced.

Asciidoctor
  • Section titles are scrubbed more thoroughly when auto-generating an ID.

  • The position of section anchors can be configured (before or after).

  • The xref macro now supports attributes (just as the link macro does).

  • The docname attribute is now set to the module-relative path of the page (minus the file extension).

  • Accurate warnings if an include tag is mismatched, unclosed, or not found (additionally, Asciidoctor now emits a warning if Antora cannot locate the include target).

  • All messages are now routed through a logger (which will hook into Antora’s logger, once implemented).

Asciidoctor.js API (for extension writers)
  • An upgrade to Opal means Asciidoctor.js no longer goes down a rabbit hole when iterating over an object’s properties.

  • Much more of the Asciidoctor API has been mapped in Asciidoctor.js, making it far easier to write extensions.

  • The extension API provides a simple mechanism for generating an extension class (as an alternative to an extension block).

  • The AbstractNode#findBy method can be short-circuited to halt the tree walk.

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

More improvements and changes

Next, previous, and parent pages

The next, previous, and parent properties are now available in the UI model so your UI can access adjacent pages in the navigation tree. See the template variables documentation to learn more.

Versioned cache folder

Antora uses a versioned cache folder for the cloned git content repositories. On first run, Antora will re-clone your content repositories into this folder. This was necessary to avoid conflicts with repositories that were cached using nodegit.

Node compatibility

Antora now works with Node 10 (and 11).

Antora playbook files in TOML

You can now write Antora playbook files in the TOML configuration language. The CSON format is no longer supported. If your Antora playbook is in CSON, you’ll need to migrate it to YAML, JSON, or TOML before using Antora 2.0.

runtime.fetch

The runtime.pull playbook key has been replaced with runtime.fetch and the --pull CLI option has been replaced with --fetch. This setting tells Antora to fetch updates to remote content repositories and grab a fresh UI bundle if marked as a snapshot. It was renamed to avoid confusion with the pull command in git. But don’t worry, the old names still work. They’re just deprecated and will be removed in the next major version.

page.origin.private

If a content source requires authentication (either because credentials were defined in the URL or credentials were requested from the credentials manager), the page.origin.private property will be set in the UI model.

page.displayVersion

The display version of a component is now accessible via the UI model using the page.displayVersion property.

page.latest

The page.versions.latest property in the UI model can now be reached using page.latest.

AsciiDoc doctype

The AsciiDoc doctype option can be safely set in the AsciiDoc configuration key. Navigation files will always be parsed using the article doctype.

default tags filter

The default tags filter for content repositories can now be set using the content.tags key in the playbook.

Known issues

Reference pruning

Issue

#374

Summary

After the switch to isomorphic-git, references are no longer pruned when the --pull option is specified. This means that if a reference is removed from the remote repository, it will not be removed from Antora’s cached version.

Workaround

You can clear Antora’s cache directory or the cache of the repository in question. We’ll restore this behavior in a future enhancement.

Broken 404 pages for sites that aren’t served from root folder

Issue

#258

Summary

If your site is not served from the root folder of a domain (such as is the case of sites running on the GitHub Pages or GitLab Pages domain), the references to UI assets and navigation links on the 404 page will not work property.

Workaround

Postprocess the 404.html page to fix the paths before publishing the site.

Self-signed certificates

Issue

#390

Summary

The HTTP client Antora uses to download the UI bundle (got) does not load the CA certificate file on the local machine. As a result, if the server hosting the UI bundle has a self-signed certificate, Antora will fail trying to download the bundle (due to the fact that Node rejects the certificate as unauthorized).

Workaround

Instruct Node not to reject unauthorized certificates by setting the environment variable NODE_TLS_REJECT_UNAUTHORIZED=0 when calling Antora.

Thank you!

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

Abel Salgado Romero (@abelsromero)

Fix wrong gulp-ci package name replacing it with correct gulp-cli MR 294

Antonio (@bandantonio)

Fix colon typo in resource id include directive MR 284
Add information about missing runtime category in the playbook configuration MR 282

Julien Grenier (@jgrenier)

Fix failing build (docker-antora) MR 5

Matthew Setter (@settermjd)

Correct reference to ui-bundle-url in the docs MR 280

@Leantricity

Fix page-to-page-xref.adoc typo MR 278

Metrics

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.

Upgrade checklist

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

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

Software Lifecycle Notices

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