What’s New in Antora 3.0

Antora 3.0.0-alpha.7

Release date: 2021.06.26 | 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.

Custom git credential manager

Upgrading isomorphic-git forced a change to how a custom git credential manager is registered. Previously, this was done using git.cores.create('antora').set('credentialManager', customCredentialManager). However, isomorphic-git no longer includes the cores (aka plugin) API, so this call is going to fail. Antora still honors the cores API, but the call to register the credential manager is now responsible for creating it (since it runs before Antora loads). Refer to Configure a custom credential manager for the latest instructions.

New documentation

Preliminary documentation for the following new features is now available:

  • The log.level playbook key specifies a severity threshold, such as debug or error, that must be met for a message to be logged.

  • The log.failure_level playbook key specifies the severity threshold that, when met or exceeded, causes Antora to fail on exit with a non-zero exit code.

  • The asciidoc.sourcemap key provides additional file and line number information about AsciiDoc blocks to Antora’s logger and Asciidoctor extensions.

Asciidoctor 2 feature changes and suggested fixes

In the previous Antora 3.0.0-alpha.3 release, support for Asciidoctor.js 1.5.9 (which provides Asciidoctor 1.5.8) was dropped and Antora switched to depending on the latest patch version of Asciidoctor.js 2.2 (which provides Asciidoctor 2.0.x).

Asciidoctor 2 introduces a few substantive changes to existing features that may impact your documentation source content or UI. See Asciidoctor Upgrade Notes to learn about the affected features and the suggested actions you should take before upgrading to Antora 3.

To test your documentation for AsciiDoc syntax problems or try out Antora’s new features before Antora 3 is final, see Upgrade Antora for instructions on how to upgrade to the latest prerelease of Antora.

Resolved issues

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

Added

Issue #767

Add built-in support for writing log messages to a file or standard stream, configured using the runtime.log.destination category in the playbook, with additional settings for buffer size, sync, and append. Map the --log-file CLI option and ANTORA_LOG_FILE environment variable to the runtime.log.destination.file key in playbook.

Issue #780

Add level_format key to log category (default: label), mapped to --log-level-format CLI option, to allow log level format to be configured. Use numeric log level in JSON log message if log level format is number.

Issue #776

Add sourcemap key to asciidoc category (default: false), mapped to --asciidoc-sourcemap CLI option, to enable sourcemap on AsciiDoc processor.

Issue #403

Log error message when target of xref is not found.

Issue #368

Catalog example and partial files that do not have a file extension (e.g., Dockerfile).

Issue #220

Add a completion status message to stdout that shows file URI to local site when terminal is a TTY (and --quiet is not set).

Fixed

Issue #771

Port fixes for include tags processing from Asciidoctor.

Changed

Antora logger

Set fatal as default value for runtime.log.failure_level; remove all, debug, and info from allowable set of values. Don’t set name on root logger so it isn’t included in raw JSON message.

Issue #785

Rename --failure-level option to --log-failure-level. Rename silent value on runtime.log.failure_level to none.

Issue #784

Remove structured as possible value of log.format, preferring json instead.

Issue #778

Configure CLI to recognize options that accept a fixed set of values and validate value before proceeding. Rename options to choices in help text. Combine choices and default value together in help text for option that accepts a fixed set of values.

Issue #776

Include line number and correct file in xref error message when sourcemap is enabled on AsciiDoc processor.

Issue #774

Upgrade git client to isomorphic-git 1.8.x and update code to accommodate changes to its API.

Issue #706

Ignore backup files (files that end with ~) when scanning content source.

Issue #769

Use converter registered for the html5 backend instead of always using the built-in HTML5 converter. Detect when registered html5 converter has changed and recreate extended converter to use it.

Issue #733

Upgrade CLI library to commander.js 7.2.

Issue #403

Change "include target" to "target of include" in error message for missing include.

Antora 3.0.0-alpha.6

Release date: 2021.06.07 | Issue label: 3.0.0

Resolved issues

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

Added

Issue #145

Introduce a new component that provides the infrastructure for logging, shaping, and reporting application messages.

All application messages (except for CLI warnings and uncaught errors) are routed through the logger. This feature is enabled by default. The logger is configured once per run of Antora by the runtime.log category in the playbook.

Messages are either emitted in a structured (JSON) log format so they can be piped to a separate application for processing/transport or in a pretty format to make them easier for an author to comprehend. But default, structured (JSON) messages are logged to stdout if the CI environment variable is set. Otherwise, pretty messages are logged to stderr.

As part of this change, messages logged by Asciidoctor are routed to the Antora logger and decorated with additional context from Antora (e.g., file, line, and include stack details).

Issue #749

Add support for proxy settings to the git client and UI downloader. Both components now use the same HTTP library (simple-get).

The git client and UI downloader honor proxy settings defined in the network category in the playbook. The http_proxy, https_proxy, and no_proxy environment variables are mapped to respective keys in the playbook.

Fixed

Issue #765

Add file info to reader before pushing include onto the stack so it stays in sync if file is empty.

This change fixes how the target of an include that follows an empty include is resolved.

Issue #764

Assign file URL to src.origin.url on virtual file if repository has no remote and not using worktree.

This change allows the location of the local git repository to be shown in log messages.

Changed

Issue #766

Report include location in log message when include tag(s) cannot be found.

This change allows the location of the include file to be shown in log messages.

Antora 3.0.0-alpha.5

Release date: 2021.05.14 | Issue label: 3.0.0

Resolved issues

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

Added

Issue #188

Add full support for resolving symlinks located in the git tree of a content source. Provide a clear error message when a broken symlink or symlink cycle is detected in the git tree.

Issue #296

Allow the component version string for a content source to be derived from the git refname.

The mapping is defined using a map of pattern and replacements on the version key on the content source in the playbook or on the version key in the component descriptor. The replacement that corresponds to first pattern that matches will be used. If no pattern is matched, or the value of version is true, the refname will be used as the version.

Fixed

Issue #747

Add full support for resolving symlinks that originate from the worktree of a local content source. Provide a clear error message when a broken symlink or symlink cycle is detected in worktree.

All symlink tests are now verified on Windows in addition to Linux.

Changed

None.

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.