What’s New in Antora 3.1

Detect and warn when an AsciiDoc extension is registered as an Antora extension, but do no skip it.

Switch from ESLint/Prettier to Biome and update code formatting accordingly.

Upgrade @antora/expand-path-helper and @antora/user-require-helper dependencies to 3.0.x in various packages.

Gracefully handle case when value of nav key in component version descriptor is not an array (content-aggregator).

Use navtitle as content of orphan breadcrumb entry instead of doctitle (aka page title) (page-composer).

Fully support static register method on Class or Object exported by extension (site-generator).

Detect and warn when an AsciiDoc extension is registered as an Antora extension, but do no skip it.

Replace "AsciiDoc extension" with "Asciidoctor extension" in log messages

Wrap legacy stream on file when preparing files for output providers; remove listeners limit. Fixes compatibility with the Antora PDF extension.

Detect (and skip) Antora extension that’s been registered as an AsciiDoc extension and log a warning (asciidoc-loader)

Detect (and skip) AsciiDoc extension registered as an Antora extension and log a warning (site-generator)

Replace new fs.Stats() with plain JavaScript object (content-aggregator, ui-loader)

Replace @vscode/gulp-vinyl-zip with low-level zip file reader using yauzl (ui-loader)

Replace @vscode/gulp-vinyl-zip with low-level zip file writer using yazl (file-publisher)

Log warning if nav entry cannot be resolved (content-classifier)

Fix page.role assignment to read value from role attribute instead of from (non-existent) docrole attribute (page-composer)

Assign empty object to stat property of output file if file does not have stat property (file-publisher)

Replace vinyl-fs#dest with internal implementation (file-publisher)

Upgrade vinyl and vinyl-fs to address security and deprecation warnings

Throw clearer error if antora.yml is empty or the data is not an object (content-aggregator)

Apply include tag filtering update from Asciidoctor (see github.com/asciidoctor/asciidoctor/pull/4233) to ported logic in Antora (asciidoc-loader)

Filter out cyclic aliases (i.e., redirect loops) (redirect-producer)

Create files streams for file publishers to process eagerly to avoid race condition (file-publisher)

Use raw value if attribute value set using --attribute option cannot be parsed as YAML (cli)

Add git.read_concurrency playbook key to control how many git indexes to load into memory at once (playbook-builder)

Add hostname to ignore list to prevent hostname property on logged error from modifying logger name (logger)

Retry failed fetch/clone operations in serial if git.fetch_concurrency > 1 and an unexpected error occurs (content-aggregator)

Fix relative path computation when path is extensionless and to matches parent folder of from

Don’t fail to load AsciiDoc if target of image macro resolves to an unpublished image

Retry loadUi in isolation after aggregateContent if network connection occurs when retrieving remote UI bundle

Try credentials from credentials store if auth fails with credentials in URL.

Consider local branches in non-managed bare repository that has at least one remote branch.

Restore error stack in log output when using pino-std-serializers >= 6.1

Fix infinite auth loop if credentials embedded in content source URL are empty and repository requires auth.

Fix crash if value of worktrees key on content source is ~ (null) and at least one branch is specified.

Add guard to prevent ContentCatalog#registerSiteStartPage from registering alias loop.

Decouple logic to compute default log format from process environment.

Preserve target when creating static route if target is an absolute URL.

Allow content aggregator to parse value of content.branches and content.tags playbook keys.

Look for IS_TTY on playbook.env in site generator to decouple check from process environment.

Use pretty log format by default if IS_TTY environment variable is set to true. Print success message if IS_TTY environment variable is set to true. See Log Format for more information.

Prevent message from ignored log message from overwriting message from next reported log message.

Define public export @antora/asciidoc-loader/include/resolve-include-file for requiring resolveIncludeFile function.

Don’t require custom output provider to return a report object.

If logger can’t be found, print error message to stderr instead of crashing during shutdown.

Log info message if no references are found for content source.

Assign edit URL of current page, if set, to page-edit-url AsciiDoc attribute. Define boolean page-origin-private AsciiDoc attribute if origin of page is private.

Attach parsed component version descriptor to descriptor property on origin object.

Add removeFile method to the content catalog and UI catalog.

Define page-component-latest-version AsciiDoc attribute with value of version string from latest component version. Define boolean page-component-version-is-latest AsciiDoc attribute if page is in latest version of component. See intrinsic page attributes for more information.

Add origins property containing unique origin objects to each entry in the content aggregate.

Resolve attribute references in AsciiDoc attributes defined in the playbook (antora-playbook.yml) and component version descriptors (antora.yml), honoring any escaped attribute references.

Define exports for all packages, locking down what paths can be required to the public API.

Include target in error message for broken or cyclic symbolic link in local content source or UI bundle directory.

Set Node.js 16.0.0 as minimum supported Node.js version. Upgrade dependencies that require Node.js > 12 and remove workarounds.

Move logic to collate AsciiDoc attributes to a helper function. Use helper function to collate AsciiDoc attributes from playbook and component version.

Add context to error and preserve cause if failure occurs when reading supplemental UI files.

Log warning message instead of throwing fatal error if file in worktree disappears or cannot be read.

Consistently format origin information in log and error messages.

Set worktree property on origin to false when branch or tag is local but not taken from worktree. Use isolated Handlebars environment instead of the default (global) environment.

Antora no longer supports Node.js < 16 (specifically dropping support for Node.js 12 and 14) since those Node.js release lines are now EOL. This change is consistent with Antora’s Node.js support policy.