Configure the Component Version Filter

By default, the exporter extension runs on the latest version of every component in the site. You can control which component versions the exporter runs on using the component versions filter in the Assembler configuration file.

component_version_filter key (category)

The component_version_filter category key groups the filters that specify which component versions the exporter extension (and hence Assembler) should run on. The result of the filtering process is always a list of component version objects.

Acceptable keys and their default values are listed in the table below.

Key Default Type Description

names

*

A picomatch pattern or an array of picomatch patterns

Patterns for matching (or filtering) component and component version names.

names

The names key is an optional key that can be set in antora-assembler.yml. It accepts either a picomatch pattern or an array of picomatch patterns. The array value can have any number of entries. Each entry in the array must be a picomatch pattern. These patterns are used to select the component versions on which Assembler runs.

A picomatch pattern can be used to specify an exact component name (e.g., component-name) or an exact component version name (e.g., 2.0@component-name). When a wildcard is present in the pattern (e.g., **), it can match multiple components and/or component versions. If a pattern matches more than one component version, a subsequent negated pattern can be used to remove matches (e.g., !component-name).

Here’s a summary of the accepted values:

*

Default. This value matches the latest version of all components. If a filter isn’t specified, the extension will automatically use this value at runtime.

**

An abbreviation of *@*, this value matches all components and versions.

component-name

This value matches the latest version of the component with this name.

*@component-name

This value matches all versions of the component with this name.

component-version@component-name

This value matches a specific version of the component with this name (i.e., the component version name).

{pattern-1,pattern-2}

An alternation pattern, this value matches either the first pattern or the second pattern. At least two or more patterns must be specified.

!component-name

This value unselects the latest version of a previously matched component.

Here’s an example that shows how to configure the exporter extension to generate exports for the last version of a component named component-name.

component_version_filter:
  names: component-name

The pattern filter can also be expressed as an array:

component_version_filter:
  names: [component-name]

To avoid YAML syntax errors, it’s best to enclose the singular value or each value in the array in single quotes. For example:

component_version_filter:
  names: ['component-name']

Here’s an example of how to generate exports for all versions of two different components:

component_version_filter:
  names: ['*@component-a', '*@component-b']

You could also express this selection using an alternation pattern:

component_version_filter:
  names: '{*@component-a,*@component-b}'

Any value can be negated by prefixing it with !. Once you select certain components and versions, you can then remove one or more of them from the list using negated entries. For example, to run the exporter extension on the last version of every component except for component-name, use the following value:

component_version_filter:
  names: ['*', '!component-name']

The picomatch patterns that Assembler recognizes are consistent with patterns used throughout Antora.