Antora is a static site generator for documentation websites that the development team has now presented in version 3.0.0 after around three years of work. Antora reads documentation in AsciiDoc format from one or more Git repositories and creates HTML files from them, which any web server can then deliver. Users of the site can find the content they want via navigation, cross-references and searches. If documentation is required broken down by software version, Antora creates individual sub-sites from various branches and tags in the Git repositories. In version 3, which is now available, there are some new functions that are intended to make working with the tool easier.
News for authors
The new release is based on Asciidoctor 2, which enables not only minor optimizations and bug fixes, but also new features such as fold-out text areas in Antora. These can initially hide tips or a solution in tutorials, for example.
As in version 2, Antora follows the “convention over configuration” approach, so that all example files for a component are located in the “examples” directory. In the past, this regularly led to the problem that source code examples were in different directories depending on the build tool, were not found there by Antora and therefore had to be stored as a copy in the “examples” directory. Version 3 now also processes Git symlinks, so that a link to files or directories can be stored in the “examples” directory. In this way, the files are available for Antora and can be used directly by the authors.
Resource IDs, with which authors can create links between components and versions, were only used in Antora 2 for cross-references to other pages. As of version 3, they can also be used consistently for references to attachments and for linked images. The file extension “.adoc” must now always be specified for cross-references to pages, since cross-references without extension were already deprecated in version 2.
All important changes for Antora 3 can also be used in the current version of the AsciiDoc plug-in for IntelliJ. It is available in the Community Edition for both paid and free JetBrains IDEs such as IntelliJ IDEA. This allows authors to complete cross-references in their development environment while writing and have them checked automatically.
Site generation news
Fixed URLs can now be stored for the latest documentation version and the latest pre-release. This makes it easier for users to set bookmarks and links always point to the latest version. In addition, a component of the documentation can be named a ROOT component, which then serves as an entry point to the documentation site.
Version 2 was already able to deal with extensions for Asciidoctor, with which, for example, the HTML generation of the content could be extended. A popular extension is examples for different programming languages in different tabs. With version 3 an API is now available for the first time to extend the site generator. This gives developers the opportunity to adapt the structure of the page and control or hide the content.
Thanks to the new API, the integration of search options has also become easier: The Antora Lunr plug-in, popular in version 2, for a client-side full-text search has been migrated to Antora 3 and is available in the standard UI. An integration of a SaaS solution such as the Algolia search is also possible, but still not included in the standard UI.
News for continuous integration and continuous delivery
Antora 3 supports Node.js versions 12 to 16 for generating the site. Any web server is still suitable for hosting the generated site – Node.js is not required.
With the update to Asciidoctor 2, warnings and error messages during the build, for example in the case of missing closed blocks, now contain the source file and line number, which makes troubleshooting easier. The site generator also outputs error messages if a cross-reference leads nowhere. With the appropriate configuration, the messages can be output in JSON format so that they can be processed further automatically. If desired, the build can also be canceled if a warning or an error occurs, so that only error-free documentation sites are published.
Also new is support for HTTP proxies during site generation, as is often required for company setups. This also allows Git repositories to be integrated that can only be accessed via a proxy.
Installation and upgrade tips
For the update to version 3, the chapter “What’s New in Antora 3.0” provides a detailed overview and an upgrade checklist. There is also an overview of the changes resulting from the update to Asciidoctor 2. In order to use all new Antora features, however, the Antora UI theme should be updated.
If you are interested in further information on getting started with Antora, you will find suitable assistance in the chapter “Install and Run Antora Quickstart”.
The Antora community meets online in the Zulip chat, where users can ask questions, which the authors or other users then answer.
outlook into the future
Although functions such as PDF generation did not make it into the new major release, the community chat provides the first examples of how this can be solved with extensions. An overview of the various extensions that have emerged in the community is still missing. Hopefully this will be added to the Antora documentation soon.
The site generator is used for documentation in an increasing number of open source projects – including Eclipse Che, Debezium, Apache Camel and Couchbase. The support of Git symlinks, through which sample code can be used independently of the storage location in documentation created with Antora, makes version 3.0 interesting for even more open source projects.
The trend towards Documentation as Code continues unabated and enables developers and technical writers to work efficiently with tried and tested tools and to provide versions of the documentation at the same time as the software.
(map)