What’s New in Antora 3.0

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

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.

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; superceded by getFiles.

Issue #689

Deprecate getAll method on UiCatalog; superceded 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; superceded by getFiles.

Issue #689

Deprecate the --google-analytics-key CLI option; superceded 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; superceded 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; superceded by latest property.

Issue #689

Remove deprecated getComponentMap and getComponentMapSortedBy methods on ContentCatalog.