By default, Antora automatically computes the edit URL for all files it takes from a remote repository or a local repository connected to a remote repository, if possible. “If possible” means this works if the remote repository is located on the primary GitHub, GitLab, Bitbucket, or Pagure hosted services. What was lacking in previous versions of Antora was support for other git hosts (e.g., on-prem GitLab) or to be able to customize or disable the value. If the automatic value of the edit URL doesn’t work in your case, you can now customize it.

You can use the edit_url key in the playbook to control the edit URL. This optional key can be set directly on the content category to apply to all content sources or on an individual content source entry to override that inherited value.

By default, the value of the edit_url is true. This value tells Antora to use the existing, built-in behavior of computing the edit URL automatically.

If the value of the edit_url is a string, it’s interpreted as a pattern. That pattern supports the following placeholders, fulfilled by the file’s origin information:

For example, to configure the edit URL to point to the view page of a file on GitLab, you’d use the following entry:

To disable the edit URL instead, set the value to tilde (~) or false.

or

As part of this change, the edit URL no longer points to the file URI when a file is taken from the worktree (local file tree). Instead, the file URI is stored separately. Both values are passed to the UI model as editUrl and fileUri, respectively. This gives the UI template control over whether to use the file URI when available, or whether to ignore it and use the edit URL instead.

The default UI has been updated to use the value of the fileUri for the edit link if set and the CI environment variable is not set (i.e., (and page.fileUri (not env.CI))). Otherwise, it falls back to using the editUrl if the repository is public (i.e., (and page.editUrl (not page.origin.private))). This update allows the default UI to work with Antora 2.2 as well as earlier versions.

To find out all the details about how this feature works, please refer to the edit URL configuration page in the documentation.

When you put a static site online, you want to provide a hint to search engines about where to crawl when indexing the site. Sometimes, you want to give them free rein. Other times, you want to tell them to back off entirely. Or, you may want to restrict access to certain portions of the site. That’s the role of the robots.txt file, found at the root of the site.

You can now use the site.robots key in the playbook file to instruct Antora to generate the robots.txt file.

If you want to grant full access, set the value to allow:

If you want to forbid access, set the value to disallow:

Any other value will be used as the contents of the robots.txt file. For more details, see configuring the robots.txt file.

Previously, to include a page (i.e., an AsciiDoc file inside the pages directory), it was necessary to mark that page as a partial. You’d mark a page as a partial by declaring the page-partial attribute in the document header. As of this release, you can use any page in the include directive by default. In other words, you no longer have to worry about marking individual pages as partials. (Under the covers, Antora automatically sets the page-partial attribute globally).

If you want to restore the previous behavior, add the following configuration to your playbook file:

If you make this change, you’ll again need to mark any page you want to include using the page-partial. You may decide to revert to the previous behavior as an optimization, since it uses slightly less memory. You can find more details about this setting in the documentation for the page-partial attribute.

In addition to filtering the lines of an include file by named tags, you can now filter lines by line numbers. This AsciiDoc feature has long been available in Asciidoctor, but was not enabled in Antora.

Line numbers are specified by the value of the lines attribute on the include directive. Line numbers, which start at 1, can be identified as individual entries or as a range. Multiple entries can be separated either by semi-colons or commas.

For example, here’s how you’d select the first line of this page:

Here’s how you’d select lines 2 through 10:

And here’s how you’d select the first line, and all the remaining lines starting at line 10:

For more information about the lines attribute on the include directive, refer to the include by line ranges section in the Asciidoctor user manual.

When you pass the --fetch flag to the antora command or set the runtime.fetch key in the playbook file to true, Antora fetches updates from all the remote git repositories. However, it wasn’t removing references (branches and tags) that had been deleted from the remote repository. Antora would still discover these references due to the stale cache. In addition to publishing content that was supposed to be removed, Antora could also fail if it found the same file in two different references (the pesky duplicate nav or page errors).

Now, Antora does a complete sync. When Antora reaches out to the remote repositories for updates, it will remove any references in the cache that have been removed from the remote repository. There’s nothing you need to do to enable this feature. It’s automatic.

To disable either tags or branches for a content source entry, you used to have to set the value to an empty array:

Now you can use the value tilde (~), which is short for null (aka nothing).

If the tags or branches key is present on a content source entry, that value takes precedence, regardless of what the value is.

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

We want to call out the following people for making contributions to this release:

The ability to use parent references in the target of the AsciiDoc image macro (e.g., image::../../../module-b/_images/image-filename.png[]) will be deprecated in Antora 3.0. You should begin replacing any such image targets with resource IDs.