What’s New in Antora 3.2

Antora 3.2.0

Release date: TBD | Issue label: 3.2.0

The primary focus of Antora 3.2 is to enhance the extension facility and to provide and refine certain API methods and endpoints to support the development of Antora extensions. This release also adds full support for using a linked worktree or submodule of a locally-cloned repository as a content source. It also adds syntax for the inclusion and exclusion matching of worktrees, a commits filter, control over the fetch depth, the ability to use the ref placeholder in the edit_url key, the implicit ROOT module, and the file property and resourceResource helper to the UI model. This version of Antora requires at least Node.js 20.

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

Resolved issues

Added

Issue #1127

Support content source root as implicit ROOT module if modules directory is absent (content-classifier).

Issue #1015

  • Emit componentsRegistered event after all components and versions have been registered (site-generator).

  • Store raw files, nav, and startPage data on partially constructed component version until processed (content-classifier).

  • Add readable property named files to component version in ContentCatalog#registerComponentVersionStartPage to get files for component version on access (content-classifier).

  • Add readable property named startPage to component version in ContentCatalog#registerComponentVersionStartPage to look up start page for component version on access (content-classifier).

  • Update ContentCatalog#registerComponentVersionStartPage to return start page (content-classifier).

Issue #535

Allow linked worktree to be used as content source; automatically resolve main repository location and remap HEAD reference in branches (content-aggregator).

Issue #1016

Add syntax to match current branch of specific worktrees in branches pattern (for inclusion or exclusion) (e.g., HEAD@5.8.x) (content-aggregator).

Issue #1208

Allow using submodule of locally-cloned repository as content source (content-aggregator).

Issue #1013

Add support for ref placeholder to insert full name of git ref (e.g., refs/heads/v4.0.x) in value of edit_url key on content source (content-aggregator).

Issue #1008

Add addSplatAlias method to ContentCatalog for adding a splat (i.e., directory) alias (content-classifier).

Issue #1021

Discover implicit site start page in component version promoted to site root (content-classifier).

Issue #1090

Add git.fetch_depth key to control how many recent commits Antora fetches from a remote repository (playbook-builder).

Issue #1165

Add file property to UI model of page (page-composer).

Issue #1167

Add built-in resolveResource UI helper to complement resolvePage UI helper (page-composer).

Issue #1106

Allow component name and version to be referenced by attributes defined in antora.yml (content-classifier).

Issue #1006

  • Use value of versionSegment property on component version in place of version in output path and URL of pages (content-classifier).

  • Set dynamic activeVersionSegment property on component version to indicate which version segment is in use (content-classifier).

Issue #831

Allow content source to be filtered by commits (playbook model only) (content-aggregator).

Issue #976

Allow extension to be switched off from CLI by negating value (playbook-builder).

Issue #1203

Add buildAlternateNavigation function for building navigation for component version from an à la carte collection of nav files (navigation-builder).

Issue #1092

Preserve order of extension from playbook when enabled from CLI if order is fixed (playbook-builder).

Issue #1211

Process role on text entry in navigation (navigation-builder).

Issue #1153

Allow file to be explicitly marked as private; not private bypasses underscore check; explicitly mark underscore file as private otherwise (content-classifier).

Issue #1220

Don’t compute and assign pub property when adding file to content catalog if pub property is falsy (content-classifier).

Issue #1221

Add createFile method to content catalog to create file without adding it to content catalog (#1221)(content-classifier).

Issue #1219

Add publishableFamilies setting on content catalog to allow custom family to be marked as publishable (content-classifier).

Issue #1225

Update ContentCatalog#getFiles to accept a predicate (i.e., filter function) to filter files (content-classifier).

Changed

Issue #1009

Remove invalid trailing slash from value of site.url when building playbook and from value of site.url after playbookBuilt event (i.e., when it’s provided by an extension) (playbook-builder).

Issue #1026

Don’t recompute resource ID on file from content aggregate if src.family is set (content-classifier).

Issue #1012

Always assign the value auth-required to origin.private if the server requests credentials, even when the credentials are embedded in content source URL (content-aggregator).

Issue #298

Use worktree from local repository even if repository has no commits (content-aggregator).

Issue #1136

Prefix name of all built-in modules with node.

Issue #1135

Monkey patch pako module to use zlib.inflate to inflate git objects (content-aggregator).

Issue #1166

Allow resolvePage and resolvePageURL helpers to accept no args (page-composer).

Issue #1125

Allow site URL to be unset using --url CLI option or URL environment variable (playbook-builder).

Issue #1175

Propagate roles and additional link properties on xref to entry in navigation model (navigation-builder).

Issue #1181

Classify attachments that don’t have a file extension (content-classifier).

Issue #1187

Use symbolic name . to refer to current worktree and /. to refer to main worktree on worktrees key (content-aggregator).

Issue #1191

Use value of require key on extension in playbook as default ID if id key not specified (playbook-builder).

Issue #1205

Format generic merging objects using YAML-like structure instead of JSON (logger).

Issue #995

Assign unique origins as set to origins property on component version; use empty set if no origins specified (content-classifier).

Issue #1111

Skip check for local branches in managed repository (content-aggregator).

Issue #1191

Use value of require key on extension in playbook as default ID if id key not specified (playbook-builder).

Issue #1145

Don’t apply camelCase transformation to descendant keys of the ext key in component version descriptor (content-aggregator).

Issue #1215

Automatically set READABLE_STREAM environment variable on process to force use of Node.js APIs (content-aggregator).

Issue #1216

Change exit code to 2 when log failure threshold is exceeded and add hint to site generation completion message (site-generator, cli).

Issue #1217

Strip xref from navigation entry if mixed with other content (navigation-builder).

Issue #1222

Skip Asciidoctor extension if it has non-compliant exports; assume it self registers (asciidoc-loader).

Issue #1223

Cite specific reason why include is unresolved when target is an absoluate file path or URL (asciidoc-loader).

Issue #484

URI decode resource reference if it contains % (asciidoc-loader).

(No issue)

  • Set Node.js 20 as minimum required version of Node.js.

  • Removed numerous runtime dependencies, including pino-pretty, sonic-boom, require-from-string, and yargs-parser.

  • Don’t assign fallback value to url property on component version if property is already set (content-classifier).

  • Print site URL instead of file URI in completion message if CI=true (site-generator).

  • Update description for extension CLI option to clarify it may be specified multiple times.

  • Include - segment in edit URL for file hosted on gitlab.com to avoid redirct.

  • Move internal second argument to ContentCatalog#addFile to transient data on src property.

  • Replace use of String#substr (deprecated) and String#slice with String#substring for more optimal string operations

Fixed

Issue #1007

Set src.version to original version segment and src.rel.version to actual version on splat alias file (content-classifier).

Issue #1115

Require YAML tag on attribute or site key value to enable YAML parsing; don’t strip quotes around value (playbook-builder).

Issue #1207

Parse arguments from CLI into an options map without modifying the values (playbook-builder).

(No issue)

  • Use consistent formatting for error messages in playbook builder (playbook-builder).

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.2.

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

Martin Mattel (@mmattel)

Add example of async function usage inside async event listener, add CI and FORCE_SHOW_EDIT_PAGE_LINK env vars to reference table, and document how to configure Antora to support the use of secure URLs that have a self-signed certificate.

Raphael (@reitzig)

Fixed an error in the edit URL documentation (!940).

@stoobie

Documented how to uninstall Antora globally (#1014).

Michael Bar-Sinai (@michbarsinai)

Updated documentation for using Antora in GitHub Actions (#1073).

Jake Cahill (@JakeSCahill1)

Add extension use case to docs for resolving attribute references in attachments.

Sturt Ison (@sturtison)

Add git branch names recommendation (#1062).

Carsten Pfeiffer (@cgpfeiffer)

Document image link=self attribute introduced by #735.

Robert (@rltbennett)

Add instructions about how to use the ROOT component and add more explanation of the relationship between the ui.bundle.snapshot and runtime.fetch keys.

Takashi Sakamoto (@takaswie)

Fulfill missing gitlab entry in table of available redirect_facility key.

Sebastian Davids (@sebastiandavids)

Add docs on how to enable soft wrapping for source blocks.