What’s New in Antora 3.0

Defer playbook freezing until after playbookBuilt event is fired.

Use RedirectMatch directive for exact directory redirects in httpd redirect file to avoid infinite redirect loop.

Patch match patterns for refname, version, and start paths to work around parsing bug in picomatch.

Keep semantic versions in descending order regardless of prerelease status.

Clone stream on virtual file so complete contents of file are written to each destination.

Drop redundant trailing slash for splat alias of ROOT component with empty version segment. Set pub URL for splat alias of ROOT component with empty version segment to / instead of /..

Fix race condition that was causing the contextClosed event to always be emitted before the sitePublished event. This affected users who used extensions that relied on these events or a script that uses the generateSite(args, env) API from the site generator.

Ignore COLUMNS environment variable if it contains a non-integer value

Make env property on playbook enumerable, but don’t freeze the value.

Include family (UI) and path in message of duplicate UI file error.

Add direct support for FORCE_COLORS=1 environment variable to enable colors in prettified log message.

Allow email address as username in content source URL defined in playbook.

Don’t escape special regex characters in target URL of nginx rewrite rule.

Introduce the Antora Logger component to provide the infrastructure for logging, shaping, and reporting application messages.

Allow extracted UI bundle to be loaded from directory.

Add full support for resolving symlinks located in the git tree of a content source.

Allow the component version string for a content source to be derived from the git refname. Set src.origin.worktree property on virtual file to null if repository is local and reference is not mapped to a worktree.

Assign author to page object in UI model

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

Log error message when target of xref is not found.

Assign primary alias to rel property on target page.

Add support for ./ token at start of path in resource ID as shorthand for current topic path.

Allow the xref macro (xref:[]) to be used to create a reference to any publishable resource, not just pages. Allow the xref attribute (xref=) on image macros to be used to create a reference to any publishable resource, not just pages.

Extract method to register start page for component version (ContentCatalog#registerComponentVersionStartPage).

Store computed web URL of content source on src.origin.webUrl property of virtual file.

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. Internally, the value is coerced to empty string for practical purposes.

Store refname of content source on src.origin.refname property of virtual file.

Add support for link=self attribute on image macros.

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

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.

Allow git plugins to be specified in the playbook using the git.plugins key.

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

Add git.fetch_concurrency key to playbook schema to control the maximum number of fetch or clone operations that are permitted to run at once.

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.

Log error if image with local target or value of xref attribute on image cannot be resolved.

Map repeatable CLI option named --extension to add an entry to or enable an existing entry in the extensions key in the playbook. Don’t register pipeline extension if extension configuration has a key named enabled with a value of false and the extension is not enabled from the CLI.

Don’t use an HTTP(S) proxy if the value of the network.no_proxy key in the playbook is *.

Add gitlab redirect facility for generating redirects that can be used with GitLab Pages, and add gitlab as a valid option for the urls.redirect_facility key.

Add a beforeValidate callback as the fourth parameter to buildPlaybook.

Emit lifecycle events for generator context (contextStarted, contextStopped, contextClosed).

Drop the component segment in the publication URL and output path of all resources in the component named ROOT.

Keep AsciiDoc source on src.contents property of virtual file if keepSource property is set in AsciiDoc config by extension.

Add the @antora/site-generator package (as a replacement for @antora/site-generator-default).

Add the @antora/file-publisher package (as a replacement for @antora/site-publisher).

Add lockVariable and removeVariable methods to the generator context to lock and remove a context variable, respectively.

Add an antora meta package that provides both the CLI and site generator. Use npm i -g antora to install globally, npm i antora to install locally, or npx antora to run without installing.

Overload the generateSite function to support the signature from Antora < 3 that builds the playbook and manages the logger.

Add dependency on @antora/site-publisher package to restore backwards compatibility with existing site generators.

Follow aliases when computing version lineage for page and canonical URL in UI model.

Upgrade to Asciidoctor.js 2.2.3. Release lock on Asciidoctor.js patch version so newer patch releases of Asciidoctor.js 2.2 are installed automatically when Antora is installed.

Only register start page for component version in ContentCatalog#registerComponentVersion if value of startPage property in descriptor is truthy. Call ContentCatalog#registerComponentVersionStartPage in content classifier to register start page after adding files (instead of before).

Don’t use global git credentials path if custom git credentials path is specified, but does not exist.

Enable more powerful pattern matching for refname patterns (branches, tags, worktrees); align with pattern matching for start paths.

Switch back to using versionless default cache folder for managed content repositories.

Add unresolved role to image if target is local and can’t be resolved.

Defer assignment of mediaType and src.mediaType properties on virtual file to content classifier. Enhance ContentCatalog#addFile to update src object if missing required properties, including mediaType.

Output version of default site generator in addition to version of CLI when antora -v is called.

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

Add support for Node.js 12 and Node.js 14.

Update default branches pattern for content sources to [HEAD, v*].

Set src.origin.url property on virtual file when repository has no remote even when using worktree. In this case, the value is the file URI for the local repository.

Report include location in log message when include tag(s) can’t be found. This change allows the location of the include file to be shown in log messages.

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.

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

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

Log unhandled error at fatal level.

Ignore backup files (files that end with ~) when reading supplemental UI files and UI bundle from directory.

Attach map of environment variables to non-enumerable env property on playbook.

Rename pipeline category key in playbook schema to antora (e.g., antora.extensions).

Rename Pipeline class to GeneratorContext. Bind the generator context to the register function of an extension unless declared as the first parameter.

Move logic for postprocessing playbook config data to beforeValidate function defined in the schema.

Ignore regex modifiers and instead enable extglob for all patterns (branches, tags, worktrees, version, start paths).

Set the component and module properties on the alias for the site start page to the value ROOT (instead of an empty string).

Rename GeneratorContext#halt to GeneratorContext#stop to more clearly convey intent.

Update GeneratorContext#stop to accept an exit code to assign to process.exitCode.

Include path of playbook file in any error message that pertains to the playbook.

Change the @antora/site-generator-default package as an alias for the @antora/site-generator package.

Change the @antora/site-publisher package as an alias for the @antora/file-publisher package.

Append /index.html to file URI in completion status message if site start page is defined.

Update the publishFiles function exported by the file publisher to accept a single catalog.

Default to json log format unless stdout is TTY (interactive terminal) or CI=true.

Enforce core YAML schema when reading YAML playbook files and values and component descriptor file.

Register Antora extensions before registering generator functions. When registering generator functions, honor any functions that have already been replaced and bypass loading corresponding built-in functions.

Update produceRedirects function to accept an array of aliases in place of the content catalog.

Restore support for the YAML merge operator in a YAML playbook file.

Set process.env as the default value for the env parameter of buildPlaybook function.

Set Node.js 12.21.0 as minimum supported Node.js version. Update Antora Docker image to use Node.js 16.

Upgrade dependencies and drop workarounds for Node.js < 12.

Use page as the default family for an include target that references a component, version, and/or module.

Change signature of internal git http plugin to accept extra HTTP headers as headers keyword argument.

Change default branches pattern for content sources to HEAD, v{0..9}* to avoid matching words that begin with v.

Use same matcher in UI loader that’s used elsewhere in Antora (picomatch).

Don’t crash if a stem block is empty.

Add support for optional option on include directive to silence warning if target is missing.

Don’t crash when loading or converting AsciiDoc document if content catalog is not passed to loadAsciiDoc.

Add redirect modifier to splat alias rewrite rule for nginx (when redirect-facility=nginx).

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.

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.

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.

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.

Port fixes for include tags processing from Asciidoctor.

If an error is thrown while loading or scanning a repository, allow any clone or fetch operations already underway to complete.

Don’t warn if a page declares the manpage doctype.

Publish dot files from UI bundle if matched by an entry in the list of static files in the UI descriptor.

End destination stream for logger in finalize call when log format is pretty.

Include source information in error message for duplicate alias when component is unknown.

Gracefully handle case when remote URL for local content source uses explicit ssh:// protocol and port.

Show location and reason of syntax error in user code when --stacktrace option is specified.

Don’t camelCase keys in value of version key on content source.

Always sort prerelease versions before non-prerelease versions.

Handle symlink target that has trailing path separator.

Configure the correct logger when Antora is installed globally. Prior to the fix, the log configuration in the playbook was being ignored if using a global Antora installation.

Use existing non-zero exit code if log failure level is met.

Align logic to register component version start page with logic to register site start page. Allow site start page to overwrite start page for versionless ROOT component.

Coerce version key in playbook or component descriptor with numeric value 0 to '0' instead of empty string.

Add context info to first line of message for any error thrown by the content aggregator.

Trap broken pipe on logger destination and silence future writes.

Don’t attempt to close logger destination if stream is already destroyed, such as in the case of a broken pipe.

Remove call to process.exit(). Instead, set and return process.exitCode.

Map log file values '1' and '2' to process.stdout and process.stderr, respectively. Previously, the logger was writing the log to files named 'stdout' and 'stderr' relative to the CWD.

Include source in warning for missing page layout.

Configure progress bar to stretch width of terminal for wide terminals.

Allow extension listeners registered using once to accept context variables.

Detect case when site start page in playbook contains module name but not component name and report appropriately.

Escape spaces in value of fileUri property in publication report when publishing to local directory.

Don’t colorize pretty log output if NO_COLOR environment variable is set.

Add missing glob-stream dependency declaration.

Sync Asciidoctor log level to Antora log level when Antora log level is debug. Set context on Asciidoctor logger before calling register function of extensions to match behavior of Asciidoctor.

Deprecate :attachmentsdir: attribute and use of link macro (link:[]) to reference an attachment; use the xref macro and the attachment’s resource ID instead.

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 (~).

Deprecate default branches pattern [master, v*] for content sources; superseded by HEAD, v{0..9}*.

Drop support for Node.js 8 and 10.

Drop support for Asciidoctor.js 1.5.9. Antora 3.0 automatically upgrades to using the latest patch release of Asciidoctor.js 2.2.x.

Remove --google-analytics-key CLI option; superseded by --key.

Remove ability to use parent references in the target of the AsciiDoc image macro (e.g., image::../../../module-b/_images/image-filename.png[]); superseded by Antora resource ID.