What’s New in Antora
Learn about what’s new in the 2.1 release series of Antora.
- Issue #466
Emit “Failed to download UI bundle: <reason>” error message when remote UI bundle can’t be found or downloaded.
- Issue #480
Resolve correct value for
- Issue #485
Remove empty embedded auth (i.e., credentials) from content source URL.
- Issue #489
Decode characters in credentials parsed from URL for private content source.
- Issue #491
Encode spaces as
file.pub.url. This ensures that the HTML page that uses such URLs will validate. As part of this change, spaces in the pathname of the site.url value are now disallowed.
- Issue #492
Enclose paths in an nginx rewrite rule in quotes to escape spaces.
The documentation pages explaining the roles of documentation components, modules, and families, and their relationship to Antora’s standardized directory structure have been extensively updated.
The component descriptor key-value pair examples have also been updated.
Most important of all, a huge thank you! to all the folks who helped make Antora even better.
- Yael Namen (@recfab)
Provided error scenario and feedback for issue #466.
- Daniel Mulholland (@danyill)
- Mateusz (@centu81)
Provided error scenario and feedback for issue #489.
Release date: 2019.09.09 | Issue label: 2.1.1
The Antora 2.1.1 patch release makes the site URL more flexible (and validates it), corrects the timestamp of files in the published archive, and fixes an inconsistency in the playbook schema.
When the site URL is set in the playbook using the
site.url key or
--url CLI option, it activates several additional features.
Those features include the sitemap, the canonical URLs, and the 404 page.
The site URL is also used when producing redirects.
However, not all these features require an absolute URL.
Some only require the pathname segment of the URL (the part after the domain name).
Therefore, Antora now allows you to set the site URL to a pathname. In that case, any feature that requires an absolute URL will remain disabled. Those features are the sitemap and the canonical URLs (as required by the powers that be). The 404 page will still be created (since it doesn’t need an absolute URL), and the pathname will also be used as the prefix for any paths in the redirect rules.
If you want the pathname to be empty, set the value to
To summarize, the site URL can be either an absolute URL (with an optional pathname) or just a pathname. The playbook builder now validates that the site URL conforms to one of these two types.
The new key to control whether the git client automatically appends the .git suffix to the content source URL if missing was defined using camelCase, as in
This naming is inconsistent with all other keys in the playbook schema.
It should have been named
As of this patch release, it now is.
In other words:
git: ensure_git_suffix: false
The incorrect name is still supported, but should be considered deprecated.
When Antora reads files from a git tree, it does not assignment a timestamp to the file, meaning the mtime is undefined. That way, when the file is written, it gets assigned the current timestamp. At least, that’s how it’s supposed to work.
What the code was actually doing was assigning an invalid date. While this wasn’t a problem for the filesystem provider, it was for the archive provider. So all the files in the archive (ZIP) file that came from the git tree (and supplemental UI files that came from the playbook) had a timestamp of the Unix epoch (shortly after Woodstock). That caused certain cloud deployers to get rather confused (and dazed?). This patch release corrects this problem so that the timestamp of the files in the archive match the timestamp of the archive itself.
- Issue #471
Files in a generated ZIP site bundle have a timestamp of the Unix epoch.
- Issue #477
Name of playbook key for controlling git suffix (ensureGitSuffix) is inconsistent.
- Issue #478
Allow site.url to be a pathname, but disable any features that require an absolute URL.
- Issue #479
Playbook builder should validate site.url.
Release date: 2019.08.27 | Issue label: 2.1.0
The Antora 2.1.0 release provides more image capabilities, adds a new page attribute and playbook key, and improves path handling for 404 pages and rewrite rules.
Antora 1.1 introduced the resource ID for referencing partial and example files stored in other modules, components, and versions. Now you can use the resource ID to reference images in the AsciiDoc image macro, too!
You no longer have to store your images and attachments inside the assets folder. These folders can be top-level folders inside a module.
modules/ ROOT/ attachments/ examples/ images/ pages/ partials/
And don’t worry if you prefer using the assets folder or currently have files in an assets folder, Antora still collects images and attachments stored in the assets folder. See Documentation Components and Repositories and Modules, Families, and Subdirectories to learn more about how to organize your documentation source files.
- Control the git repository URL suffix with ensureGitSuffix
The new playbook key
ensureGitSuffixinstructs the git client to automatically append .git to the repository URL if it is absent. You don’t have to add this key to your Antora playbook if you’re using GitHub or GitLab because Antora automatically sets
trueby default. However, if you use Team Foundation Server (TFS) or Azure DevOps, set
ensureGitSuffix: falseunder the
gitcategory of your playbook if your content source repositories fail to clone.
- Access implicit page attributes from navigation files
Antora’s implicit page attributes can now be used in AsciiDoc navigation files.
- Unresolved cross references and their link text
The link text of an unresolved page reference is now displayed with the page ID when an xref can’t be resolved.
- Access a page’s display version
The component display version is now accessible via the implicit page attribute
page-component-display-version. This attribute contains the display version value found in the component descriptor (antora.yml).
- 404 pages and site paths
Antora automatically prepends the site path (pathname of site URL) to
uiRootPathon the 404 page.
- Issue #258
The pathname of the site URL (site path) is now assigned to the
site.pathproperty in the UI model. An empty string is used if the site URL is not set or the pathname is
/. To get the full fix, you must update your UI.
- Issue #468
A site URL’s trailing slash is now removed before it’s used to compute rewrite rules.
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.