What’s New in Antora 3.1

Antora 3.1.7

Release date: 2024.01.02 | Issue label: 3.1.7

Resolved issues

Changed

Issue #1099
  • Preserve all information in wrapped error (content-aggregator, ui-loader, file-publisher)

Issue #1098
  • Upgrade isomorphic-git to incorporate patch for properly handling network error (content-aggregator)

  • Add cause in log message when retrying failed fetch/clone operations in series (content-aggregator)

Issue #1101
  • Clear timeout and keep-alive settings on git HTTP connections that don’t use custom agent (content-aggregator)

(No issue)
  • Don’t retry failed clone/fetch operation if playbook only has one content source URL (content-aggregator)

Antora 3.1.6

Release date: 2023.12.19 | Issue label: 3.1.6

Resolved issues

Added

Issue #1096

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

Changed

Issue #1096
  • Change default value of git.fetch_concurrency to 1 (playbook-builder).

  • Flag git clone/fetch error as recoverable if an unexpected network error occurs (content-aggregator).

  • Decouple step to load (fetch or clone) repositories from step to scan repositories to discover references and start paths and collect files (content-aggregator).

(No issue)
  • Don’t read git tree twice if start path is empty; add dirname to tree object in same function (content-aggregator).

  • Fill in progress bar with incomplete marks if cloning a repository fails (content-aggregator).

  • Mention that credentials may have been rejected if server requests them, then sends 404 response (content-aggregator).

Fixed

Issue #1070

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

Issue #1096

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

Antora 3.1.5

Release date: 2023.11.22 | Issue label: 3.1.5

Resolved issues

Changed

Issue #1094

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

Change gulp-vinyl-zip dependency to @vscode/gulp-vinyl-zip to remove warning (no functional changes).

Fixed

Issue #1092

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

Issue #1095

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

Antora 3.1.4

Release date: 2023.06.07 | Issue label: 3.1.4

Resolved issues

Fixed

Issue #1063

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

Issue #1064

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

Antora 3.1.3

Release date: 2023.04.02 | Issue label: 3.1.3

Resolved issues

Fixed

Issue #1049

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

  • Correctly handle connection error when retrieving remote UI bundle

  • Do not fail to load AsciiDoc if pub or pub.moduleRootPath properties are not set on virtual file

Antora 3.1.2

Release date: 2022.10.28 | Issue label: 3.1.2

Resolved issues

Fixed

Issue #1010

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

Issue #1018

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

Issue #1020

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

Issue #1022

Decouple logic to compute default log format from process environment.

Issue #1024

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

Issue #1025

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

Site generator

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

Antora 3.1.1

Release date: 2022.09.21 | Issue label: 3.1.1

Resolved issues

Changed

Issue #1004

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.

Fixed

Issue #1003

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

Update to Issue #984

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

Site generator

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

CLI

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

Antora 3.1.0

Release date: 2022.08.22 | Issue label: 3.1.0

The highlights of the Antora 3.1.0 release include:

You can find a summary of the issues resolved in this release below.

Resolved issues

Added

Issue #221

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

Issue #354

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.

Issue #525

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

Issue #814

Add removeFile method to the content catalog and UI catalog.

Issue #921

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.

Issue #978

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

Issue #981

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

Issue #984

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

Issue #988
  • Add reftype key with value of branch or tag to source object in structured log message.

  • Add reftype property to origin object to explicitly identify type of git reference (branch or tag).

  • Add remote key with value of remote tracking branch to source object in structured log message, if applicable.

  • Add remote property to origin object to identify a remote tracking branch.

  • Add local key with path of local repository to source object in structured log message, if applicable.

Changed

Issue #900

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

Issue #979

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

Issue #982

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

Issue #985

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

Issue #986

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

Issue #988

Consistently format origin information in log and error messages.

Issue #993

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.

Fixed

  • Don’t append undefined after path of file in stack in pretty log format if line is missing.

  • Make warning message about missing page layout consistent with other log messages.

Removed

Node.js 12 and 14 support

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.

Antora 2 is EOL

Antora 2 is EOL. Review the checklist on Upgrade Antora to learn about what changes you should make to your source content, including AsciiDoc syntax and Asciidoctor updates introduced in Asciidoctor 2.2, and Antora configuration prior to upgrading to from Antora 2 to Antora 3.1.

Thank you!

Most important of all, a huge thank you! to all the folks who helped make Antora even better. The Antora community has provided invaluable feedback and testing help during the development of Antora 3.1.

We also want to call out the following people for making contributions to this release:

Gautier de Saint Martin Lacaze (@jabby)

Add removeFile method to contentCatalog and uiCatalog (#814).