What’s New in Antora

Antora 2.3.3

Release date: 2020.05.30 | Issue label: 2.3.3

Resolved issues

Fixed

Issue #639

Fix crash computing canonical URL for page that only exists in prerelease version.

Thanks

A huge thanks to James Elliott (@DeepSymmetry) for suffering through this bug and helping us solve the case of the missing scenario in the test suite.

Antora 2.3.2

Release date: 2020.05.24 | Issue label: 2.3.2

Highlights

Fix regression when resolving page ID with version and no file extension

If the page ID for an xref had a version but no file extension (e.g., 2.0@page), the page ID would not resolve. This happened because the . in the version number was confused as that start of a file extension. Thus the automatic .adoc file extension was not added and the page ID would not match an existing page.

What this fix does not solve is when the page (i.e., relative path) part of the page ID has a . but no file extension (e.g., something-2.0). This is an ambiguous scenario. In this case, you will have to update the page ID to include the .adoc file extension manually (e.g., something-2.0.adoc).

Keep in mind that in Antora 3, all page IDs must have a file extension. So while this regression has been corrected, this case will not resolve in the future.

Support image xref to page ID with fragment

Support for the xref attribute on images was added in Antora 2.3. However, if the page ID included a fragment identifier (e.g., page.adoc#anchor), the value would not be processed as a page ID. This has now been fixed.

Resolved issues

Fixed

Issue #635

Fix cases when page ID with no file extension fails to resolve.

Issue #636

Process image xref that points to page ID with fragment.

Thanks

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

Antora 2.3.1

Release date: 2020.04.29 | Issue label: 2.3.1

Notices

When Antora 2.3.1 was first released, there was a bug in one of the libraries (gulp-vinyl-zip) that caused Antora running on Windows to write files from the UI bundle to the published site with the ReadOnly attribute set. This bug, in turn, caused Antora to crash when generating the site a second time without using --clean flag. Adding the --clean flag to the antora command would circumvent the issue. Fortunately, this workaround is no longer required. This bug has been fixed in a patch release.

To apply the fix, uninstall Antora (specifically @antora/site-genrator-default) and install it again. For details about this problem, and a reference to the upstream issue, refer to issue #631.

Thanks to Chris Jaquet (@chrisjaquet) for recognizing this issue and providing the necessary information to help us resolve it.

Highlights

Smarter pagination

In tandem with this release, we added a pagination widget to all pages when using the default UI. This pagination widget allows readers to navigate between adjacent pages (i.e., previous and next page navigation). The change also includes adding the corresponding next and prev SEO pagination links to the head of the HTML document.

This functionality is currently hidden behind a feature flag. To enable it, set the page-pagination attribute in your playbook (or anywhere an AsciiDoc document attribute can be set).

While developing this functionality, we discovered a few problems with how the page.previous and page.next properties in the UI model were being computed:

  • If the next item in the navigation tree is a fragment of the current page, the pagination widget would get stuck on the current page (since the next property referred back to the current page).

  • If the previous item in the navigation tree is a fragment of the previous page, the pagination widget would jump to the fragment on that page, but from there jump to its previous page, skipping over all other fragments (which simply isn’t intuitive).

  • The next page for the component version start page would not be set if the start page is not present in the navigation tree.

  • Conversely, the previous page for the first page in the navigation tree would not be set to the component version start page.

All of these issues have been resolved.

As a general rule of thumb, we recommend avoiding the use of fragments in the site navigation since it mixes static and interactive models. It’s best to rely on the sidebar TOC to provide navigation within the page.

Greater portability

One of Antora’s dependencies was limiting the platforms on which Antora could be installed. This dependency (deep-freeze-node) was removed and replaced with an internal implementation (which turned out to be 5 lines of code). It should now be possible to install Antora on any platform on which Node runs.

The general policy of Antora is to avoid dependencies wherever possible. This change is not only consistent with that policy, but provides a concrete example for why we follow it.

robots.txt generated when site URL is a pathname

If the site URL is a pathname (e.g., /) rather than an absolute URL (e.g., https://example.org), the robots exclusion file (i.e., robots.txt) will still be generated. The robots.txt doesn’t require an absolute URL. Thus, it’s enough for the site URL to be set to any allowable value to serve as a hint that the file should be generated.

Documentation changes

The site URL, which is defined by the playbook, implicitly controls whether or not certain functionality in Antora is enabled. The relationship between this setting and the functionality is now more clear. Specifically, the documentation explains what impact setting the site URL has and lists all the ways it’s used. It also explains the difference between using an absolute URL and a pathname, which functionality requires the former, and when and how a pathname is required in either case.

Several updates have also been made to the default UI which impact the appearance of the documentation. In particular, hyphenation has been disabled for monospaced phrases. This change will avoid confusion by removing erroneous hyphens in the option names shown on the Command Line Interface (CLI) Reference page.

Resolved issues

Changed

Issue #623

Set page.next in UI model for component version start page to first page in navigation tree if start page not found in navigation tree.

Issue #623

Set page.previous in UI model for first page in navigation tree to component version start page.

Fixed

Issue #622

Skip over references to current page when computing page.next property for UI model.

Issue #624

Skip over references to fragments of previous page when computing page.previous property for UI model.

Issue #625

Generate robots exclusion file (robots.txt) if site URL is set to any allowable value.

Issue #621

Remove deep-freeze-node dependency (which was limiting that platforms on which Antora could be installed) and replace with internal implemenation.

Thanks

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:

Ewan Edwards (@eedwards)

For submitting the MR for the SEO pagination links in the head and providing inspiration for the design of the pagination widget.

Daniel Mulholland (@danyill)

For providing feedback and critique about the previous and next values for pages and for testing the navigation widget.

gotwf (@gotwf)

For rediscovering the compatiblity problem with deep-freeze-node and reminding us to replace it.

Antora 2.3.0

Release date: 2020.04.23 | Issue label: 2.3.0

Highlights

Declare attributes per component version

You can now set or unset attributes on all pages in a single component version by defining them in the antora.yml file for that component version. Component version attributes can be built-in, custom, or page attributes. These attributes are applied (either available or, if unset, unavailable) on all of a component version’s pages according to the attribute precedence rules. Here’s an example to give you an idea of how this looks:

Example 1. antora.yml that defines AsciiDoc document attributes for a component version
name: light
title: Data Light
version: '2.3'
asciidoc:
  attributes:
    listing-caption: false
    table-caption: Data Set@
    hide-uri-scheme: ''
    toc: ~
    page-level: Advanced
    page-category: 'Statistics, Cloud Infrastructure'

Since attributes can now be defined at multiple levels, Antora 2.3 adds the ability to soft set and unset site attributes as well as component version attributes.

With this improved scoping and tuning, page attributes are now more versatile. One of the primary roles of page attributes is to pass metadata about the page to the UI template via the UI model. The UI template can use the information provided by the page attributes in a variety of ways, from populating metadata in the published page to toggling or configuring behavior in the UI.

The new start_paths playbook key for content sources

The new start_paths key allows you to specify multiple content source roots per reference (branch or tag) of a content source. In other words, you can put multiple components or component versions—​each with its own antora.yml file—​in a single branch or tag of a repository, and define them using a single content source entry in your playbook.

In addition to exact paths, the start_paths supports discovery by accepting glob patterns, including wildcards, braces, and negated patterns. See Multiple Start Paths to learn more.

Page aliases work in xrefs

The target of an xref macro can now be a page alias, which is then transparently resolved to its corresponding page. Page aliases, which are expressed using the same syntax as a page ID, are defined using the page-aliases attribute in the document header. See Set Up URL Redirects with page-aliases to learn more.

Antora now uses the target page’s reftext when the link text in an xref macro isn’t specified. For instance, the following xref example doesn’t have any link text specified.

See xref:component-prerelease.adoc[].

But notice in the output below that Antora automatically used the target page’s title to fill in the link text when it generated the site.

By default, the reftext attribute is assigned the page’s title as its value. You can also assign a page a custom reftext value using an attribute entry.

Xrefs in navigation files behave the same way with one additional feature. Navigation files first look for the value of the navtitle attribute of the target page to populate the link text. If the navtitle attribute isn’t set, then the page’s reftext value is used instead. You never have to explicitly set reftext or navtitle unless you want to customize the default xref link text used in a page or navigation file.

xrefs can target non-AsciiDoc-based pages

If you’re using a custom generator to register non-AsciiDoc page files (such as HTML files), you can now use the xref macro to link to these pages. The syntax looks just like an xref to an AsciiDoc-based page, except the target must end in .html# instead of .adoc (e.g., xref:the-page.html#[The Page]). This feature is mostly forward looking for when Antora supports importing and processing prepared content, but can be useful to have now if you’re building on top of Antora.

On this page widget

The default UI now offers an “on this page” widget (aka TOC). You can see it on this page. The TOC lists all the section titles on the page down to the specified level and features a scroll spy that shows which section is currently active. When the page is not wide enough (such as on a mobile screen), the TOC is shown below the page title instead of in the sidebar.

The TOC is enabled by default. Here are ways you can configure the sidebar TOC:

  • Configure the text of the heading shown above the TOC using the page attribute named page-toctitle (default: "Contents")

  • Set the number of levels tracked by the TOC using the page attribute named page-toclevels (0 - 3) (default: 2)

  • Disable the TOC per page (or side-wide) by setting the page attribute named page-toclevels to -1

  • Alternately, disable the TOC by adding the -toc class to the <body> element in the HTML template

You can also control where the embedded TOC is inserted by adding the class is-before-toc to an element after the doctitle (selector: h1.page). The embedded TOC is not added if an element is found with the ID toc.

If you want to add the TOC to your own UI, feel free to grab the MPL-2.0-licensed 02-on-this-page.js script and customize it to suit your needs pursuant to the license terms.

Resolved issues

Added

Issue #251

Allow attributes to be scoped per component version. Add support for attributes to be set and defined in the component version descriptor (antora.yml).

Issue #310

Add function for extracting metadata from the AsciiDoc header. Use automatic reference text (i.e., reftext) if contents of page xref is empty in a page or resource file. Use automatic reference text (i.e., navtitle attribute or reftext) if contents of page xref in navigation file is empty.

Issue #328

Expose the content catalog’s public API to the UI model as the contentCatalog template variable. Add the built-in helpers resolvePage and resolvePageUrl to resolve pages and their publish URLs in UI templates. resolvePage can resolve virtual file by setting model=false.

Issue #495

Add the start_paths playbook key that allows a content source (url + branch/tag) to map to more than one content source root. Allow start_paths key to support glob patterns (wildcards and brace expressions). Implement scan + filter logic for glob patterns specified in start_paths key for both git tree and filesystem worktree. (@djencks)

Issue #330

Add support for xref attribute on image macros to reference an internal anchor or page.

Issue #379

Register alias to start page from index page of component version if index page is missing.

Issue #486

Add --key option to generate command to define entries for the schemaless site.keys. The option can be specified multiple times.

Issue #537

Add getPages() method to content catalog to retrieve all pages, which accepts an optional filter function.

Issue #543

Map asciidoc property on component to asciidoc property on latest version of component.

Issue #555

Add relativize as built-in UI helper.

Issue #568

Assign value of family-relative path of page to relativeSrcPath property on page UI model and page-relative-src-path attribute on AsciiDoc document.

Issue #578

Assign the SHA-1 commit hash for the content source ref (branch or tag) to the page-origin-refhash attribute on document unless page is taken from worktree. Assign the SHA-1 commit hash for the content source ref (branch or tag) to the src.origin.refhash property on the virtual file unless file is taken from worktree. Make refhash available as a template variable in the edit URL pattern.

Issue #586

Allow the target of an xref to be a page alias. Load the AsciiDoc header for all pages before any page is converted so xref can reference page alias. If ContentCatalog#resolvePage cannot locate page, look for an alias and dereference if found.

Issue #593

Map title property on file to AsciiDoc doctitle.

Issue #594

Use target page ID as fallback content for unresolved or invalid xref.

Issue #192

Add Apache httpd redirect facility. (@djencks)

Issue #437

Map role on AsciiDoc document to page.role in UI model.

Fixed

Issue #524

Restrict start_page value to a page that belongs to that component version.

Issue #556

Use state file to verify repository in cache is valid; reclone repository if file is missing (i.e., corrupt).

Issue #517

Verify downloaded UI bundle is a valid zip file before caching. Throw an error if invalid.

Issue #565

Prevent latest page version from being newer than latest component version in UI model.

Issue #613

Declare the opal-runtime package as a direct dependency (to satisfy Yarn 2).

Changed

Issue #121

Don’t sort component version entries in the content aggregate; leave them in the order they’re discovered.

Issue #494

Add trailing newline to all generated files. (@djencks)

Issue #251

Apply camelCase transformation to keys in the component version descriptor file, excluding the asciidoc key. Pass the site-wide AsciiDoc config to the classifyContent function.

Issue #486

Make site.keys map in playbook schemaless and ensure the values are primitive. The option can be specified multiple times.

Issue #495

Condense repeating slashes in start_path value(s).

Issue #516

Preserve stack from got (HTTP client) error when downloading UI.

Issue #517

Report clearer error when local or cached UI bundle is not valid or cannot otherwise be read.

Issue #531

Add start path to error message thrown while aggregating files. Consistently enclose details in error message in round brackets.

Issue #532

Report clearer error if component version descriptor file cannot be parsed.

Issue #538

Rename getFiles() method on content catalog and UI catalog to getAll(); retain getFiles() as deprecated method. Call getAll() method on catalog if available, otherwise getFiles().

Issue #551

Upgrade Handlebars to fix performance regression.

Issue #616

Add template path and cause to Handlebars error.

Issue #561

Modify ContentCatalog#registerComponentVersion to return component version added.

Issue #562

Modify ContentCatalog#addFile to return file added.

Issue #563

Don’t assign out property when adding a file to the content catalog if out property has falsy value.

Issue #564

Don’t relativize absolute pub URL. Don’t prepend site URL to absolute canonical URL.

Issue #581

Ignore dot (hidden) folders when matching start paths unless pattern itself begins with a dot.

Issue #595

Modify netlify redirects to be forced as recommended by Netlify.

Issue #597

Change ContentCatalog#resolvePage to delegate to ContentCatalog#resolveResource.

Thanks

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:

Antonio (@bandantonio)

For writing the Install and Run Antora Quickstart guide and assisting Matthew Setter with the redirect facility documentation. #299

Rob Donnelly (@rfdonnelly)

For fixing typos in the Run Antora in a Container page. !434

James Elliott (@DeepSymmetry)

For reviewing the new attributes pages and fixing typos. !513

Guillaume Grossetie (@g.grossetie)

For redoing the UI loader tests to dynamically construct UI bundles and test them (#553), and for fixing the nvm installation link on the Linux and macOS Requirements pages (!405).

David Jencks (@djencks)

For making numerous improvements to Antora’s documentation, including (but not limited to) clarifying component version sort order and distributed component versions, providing tips for the start_path key and component and version names, and adding filtering by line numbering information.

For implementing trailing newlines on generated files (#494), the start_paths playbook key (#495), and the Apache httpd redirect facility (#192).

For documenting the page-aliases attribute. #509

Jared Morgan (@jaredmorgs)

For taking on the herculean task of documenting the start_paths feature. #576

Daniel Mulholland (@danyill)

For adding documentation about developing Antora with Docker and Gulp test errors to the contributing guide. #388

Andreas Offenhaeuser

For documenting how to include navigation content. !325

Alexander Schwartz (@ahus1)

For fixing broken anchors in the documentation. !489

Matthew Setter

For documenting the redirect facility and assisting Antonio with the Antora quickstart guide. !281

Ben Walding (@bwalding)

For documenting the component version descriptor prerelease key. Commit ad7e039e

Anthony Vanelverdinghe (@anthonyv.be)

For editing the How Antora Can Help page. #518

Yoginth

For fixing typos in the package comments, test cases, and releasing guide. !433

Deprecations scheduled for Antora 3.0

Per the normal supported platforms policy, support for Node 8, and likely Node 10 as well, will be dropped.

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 removed in Antora 3.0. You should begin replacing any such image targets with resource IDs.

Antora has added the .adoc file extension to a page coordinate in page aliases and xrefs whenever it wasn’t specified by the writer. This fallback mechanism will be deprecated in Antora 3.0 to make way for using non-AsciiDoc pages in the xref facility. You should review the page IDs in your xrefs and page-aliases attributes to ensure the .adoc extension is specified.

The classifyContent function will expect the site-wide AsciiDoc config as the third argument.

The following deprecated methods will be removed from the ContentCatalog: getComponentMap, getComponentMapSortedBy, and getFiles.