What’s New in Antora 3.0

Antora 3.0.0-alpha.4

Release date: 2021.05.01 | Issue label: 3.0.0

Deprecations and breaking changes notice

The following deprecations and breaking changes will be final with the release of Antora 3.0.

Default branches pattern

If the branches key is absent on both the content key and the content source, Antora will use the default branches pattern. This pattern has been changed from [master, v*] to [HEAD, v*].

HEAD is a symbolic name that refers to the default branch for remote repositories (as set on the git host) and the current branch for local repositories. It’s very unlikely this will cause a change when using remote repositories. For local repositories, it may result in the worktree being used in cases it wasn’t previously.

Using worktrees

It’s now possible to use linked worktrees with Antora. A linked worktree allows a user to keep multiple branches checked out at once. (In other words, have one worktree per branch). Linked worktrees can be very useful for editing content across branches.

By default, Antora will only use the main worktree (i.e., worktrees: .), as it has always done. If you set the worktrees key on the content source to true, Antora will automatically discover and use linked worktrees as well. To give you even more control, you can filter which linked trees are discovered by specifying a pattern (e.g., v2.*).

To disable use of the main worktree, either set the worktrees key to false or only specify a pattern (e.g., *). This is an alternative approach to pointing the content source directly at the .git folder to disable the main worktree, as previously recommended.

If you want to use the main worktree and filter the linked worktrees, add . as the first entry in the value (e.g., ., v2.*).

Resolved issues

The added features and changes described below are in ALPHA and subject to change.

Added

Issue #742

Automatically detect and use linked worktrees registered with a local content source (i.e., a local git clone).

Issue #743

Allow worktrees to be filtered or disabled using the worktrees key on the content source. This is an alternative approach to pointing the content source directly at the .git folder as previously recommended.

Fixed

Issue #745

Upgrade marky dependency to allow isomorphic-git to work on Node.js 16. Node.js 16 has also been added to the CI matrix so the test suite is run on Node.js 16 nightly.

Issue #739

Provide fallback link text for an xref when the target matches relative src path of current page. Previously, the link text would end up being [] in this scenario.

Issue #700 (revisited)

Fix error message from being printed twice in certain cases when --stacktrace option is passed to CLI.

Changed

Issue #522 (revisited)

Release lock on Asciidoctor.js patch version so newer patch releases of Asciidoctor.js 2.2 are installed automatically when Antora is installed.

Issue #737

Update default branches pattern for content sources to [HEAD, v*].

Antora 3.0.0-alpha.3

Release date: 2021.04.15 | Issue label: 3.0.0

Deprecations and breaking changes notice

The following deprecations and breaking changes will be final with the release of Antora 3.0.

Dependencies

Antora now automatically depends on the latest patch version of Asciidoctor.js 2.2 (e.g., 2.2.3). Support for Asciidoctor.js 1.5.9 has been dropped.

Specifying the versionless component version

Since the first release of Antora, the version master has been given special meaning to identify a versionless component version. Using that term for this purpose was a mistake and we’re correcting it.

When a component version is “versionless”, it means the URL for that component version and its resources do not have a version segment (e.g., /component-name/module-name/page-name.html instead of /component-name/module-name/version-name/page-name.html). In Antora 3.0, we’re deprecating the use of the version master for this purpose. The reason we’re phasing out this term is because it’s not descriptive, it infers that the version is coupled to the branch (which it’s not), and it glorifies an immoral system based on human exploitation. In short, the term just isn’t appropriate and we want to move away from it.

Instead, you should identify a versionless component version by assigning the tilde symbol (~) (shorthand for null) to the version key in the component descriptor (i.e., antora.yml).

Example 1. antora.yml for a versionless component version
name: component-name
version: ~

As expected, when the version key is assigned ~, Antora doesn’t include the version segment in the component version’s page URLs (e.g., /component-name/module-name/page-name.html). Although rare, if you ever need to refer to a resource in a versionless version, you can do so using the keyword in the resource ID (e.g., @page.html).

Resolved issues

The added features and changes described below are in ALPHA and subject to change.

Added

Issue #669

Allow value of the version key in a component descriptor file to be ~ (shorthand for null) to indicate a versionless component version. Null is assigned using the tilde symbol (~) or the keyword null. Empty string is also accepted, but not as elegant. Internally, the value is coerced to empty string for practical purposes.

Issue #669

If the version is empty (version: ~), don’t add a version segment to pub.url and out.path (even if it’s a prerelease).

Issue #669

Sort the versionless version above all other versions (semantic and non-semantic) that belong to the same component. Assign the fallback default as the display version if the version is empty and the display_version key isn’t specified. If prerelease is set in the component descriptor to a string value, use that as the fallback display version instead.

Issue #669

If the version is not specified on an alias that specifies an unknown component, set the version to empty string. We expect this change to be internal and not affect any sites.

Issue #669

Add support for keyword to refer to an empty version in a resource ID (e.g., @page.html).

Changed

Issue #522

Upgrade to Asciidoctor.js 2.2.3 and allow installation of newer patch versions automatically.

Issue #731

Add support for Node.js 12 and Node.js 14. Run tests nightly on Node.js 12 and 14 (in addition to Node.js 10).

Fixed

Issue #663

Don’t crash if a stem block is empty.

Deprecated

Issue #669

Deprecate the value master to represent an empty (versionless) version when assigned to the version key in a component descriptor file; replace with the tilde symbol (~).

Removed

Issue #522

Drop support for Asciidoctor.js 1.5.9. By using Antora 3, you will automatically be upgraded to using Asciidoctor.js 2.2.x.

Antora 3.0.0-alpha.2

Release date: 2021.04.08 | Issue label: 3.0.0

Resolved issues

The added features and changes described below are in ALPHA and subject to change.

Added

Issue #150

Allow extracted UI bundle to be loaded from directory.

Issue #694

Store refname of content source on src.origin.refname property of virtual file.

Fixed

Issue #698

Add redirect modifier to splat alias rewrite rule for nginx (when redirect-facility=nginx).

Issue #700

Show error message with backtrace (if available) when --stacktrace option is set, even if the stack property is missing.

Removed

Issue #689

Remove deprecated page-relative attribute; superseded by page-relative-src-path.

Antora 3.0.0-alpha.1

Release date: 2020.09.29 | Issue label: 3.0.0

Deprecations and breaking changes notice

The following deprecations and breaking changes will be final with the release of Antora 3.0.

Syntax

The ability to use parent references in the target of the AsciiDoc image macro (e.g., image::../../../module-b/_images/image-filename.png[]) has been removed. Replace any such image targets with resource IDs before upgrading. Additionally, if an image cannot be resolved, its path will be passed through as entered rather than being prefixed with the imagesdir value (_images/).

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 has been deprecated in Antora 3.0 to make way for using non-AsciiDoc pages in the xref facility. Review the page IDs in your xrefs and page-aliases attributes to ensure the .adoc extension is specified before upgrading.

Dependencies

Support for Node.js 8 has been dropped; the minimum required version is now Node 10.

See the Removed and Deprecated sections for the entire list of breaking changes.

Resolved issues

The added features and changes described below are in ALPHA and subject to change.

Added

Issue #314

Add urls.latest_version_segment_strategy key to playbook schema.

Issue #314

Add urls.latest_version_segment and urls.latest_prerelease_version_segment keys to playbook schema.

Issue #314

Replace latest version and/or prerelease version segment in out path and pub URL (unless version is master) with symbolic name, if specified.

Issue #314

Define latestPrerelease property on component version (if applicable) and use when computing latest version segment.

Issue #314

Use redirect facility to implement redirect:to and redirect:from strategies for version segment in out path / pub URL of latest and latest prerelease versions.

Issue #355

Assign author to page object in UI model

Issue #425

Assign primary alias to rel property on target page.

Issue #605

Extract method to register start page for component version (ContentCatalog#registerComponentVersionStartPage).

Issue #615

Store computed web URL of content source on src.origin.webUrl property of virtual file.

Changed

Issue #314

Register all component versions before adding files to content catalog.

Issue #425

Follow aliases when computing version lineage for page and canonical URL in UI model.

Issue #598

Upgrade dependencies.

Issue #605

Only register start page for component version in ContentCatalog#registerComponentVersion if value of startPage property in descriptor is truthy.

Issue #605

Call ContentCatalog#registerComponentVersionStartPage in content classifier to register start page after adding files (instead of before).

Issue #681

Don’t use global git credentials path if custom git credentials path is specified, but does not exist.

Issue #682

Replace the fs-extra dependency with calls to the promise-based fs API provided by Node.

Issue #689

Require page ID spec for start page to include the .adoc file extension.

Issue #689

Require page ID spec target in xref to include the .adoc file extension.

Issue #689

Make check for .adoc extension in value of xref attribute on image more accurate.

Issue #689

Interpret every non-URI image target as a resource ID.

Issue #689

Rename exported resolveConfig function in AsciiDoc loader to resolveAsciiDocConfig; retain resolveConfig as deprecated alias.

Issue #693

Defer assignment of mediaType and src.mediaType properties on virtual file to content classifier.

Issue #693

Enhance ContentCatalog#addFile to update src object if missing required properties, including mediaType.

Fixed

Issue #678

Add support for optional option on include directive to silence warning if target is missing.

Issue #680

Show sensible error message if cache directory cannot be created.

Issue #695

Don’t crash when loading or converting AsciiDoc document if content catalog is not passed to loadAsciiDoc.

Deprecated

Issue #689

Deprecate getAll method on ContentCatalog; superseded by getFiles.

Issue #689

Deprecate getAll method on UiCatalog; superseded by getFiles.

Issue #689

Deprecate exported resolveConfig function in AsciiDoc loader.

Issue #689

Deprecate use of page ID spec without .adoc file for page alias.

Issue #689

Deprecate use of non-resource ID spec (e.g., parent path) as target of include directive.

Issue #689

Deprecate getAll method on site catalog; superseded by getFiles.

Issue #689

Deprecate the --google-analytics-key CLI option; superseded by the --key option.

Removed

Issue #679

Drop support for Node.js 8 and set minimum required version to 10.

Issue #689

Remove pull key from runtime category in playbook; superseded by fetch key.

Issue #689

Remove ensureGitSuffix key from git category in playbook file (but not playbook model); renamed to ensure_git_suffix.

Issue #689

Remove fallback to resolve site-wide AsciiDoc config in classifyContent function.

Issue #689

Drop latestVersion property on component version object; superseded by latest property.

Issue #689

Remove deprecated getComponentMap and getComponentMapSortedBy methods on ContentCatalog.