Tags

The tags key accepts a list of exact tag names and patterns for matching tag names.

We generally recommend against pulling documentation from tags. If you do use tags, we recommend using dedicated documentation tags rather than reusing tags for software releases. You can read more about our philosophy regarding documentation versioning on the Content Source Versioning Methods page.

tags key

The tags key is optional and can be specified directly on the content key or on a url key. It accepts a list of tag name patterns. Each value can be an exact tag name (e.g., v2.3.1, v3.9.4, etc.) or a pattern (e.g., v2.*, v@({1..9})*({0..9}).({0..9}).x+, etc.). The list of tags can also be a combination of these value types.

Example 1. antora-playbook.yml

content:
  sources:
  - url: https://git-service.com/org/repo-z.git
    tags: [90.0, 93.0] (1)
  - url: https://git-service.com/org/repo-x.git
    tags: [95.0, releases/*, '!v1.*'] (2)
    branches: ~ (3)

1	Enclose multiple values in a set of square brackets (`[]`). Separate each value with a comma (`,`).
2	Exact tag names and glob patterns can be assigned to a `tags` key.
3	Disable the default branches filter by setting `branches` and assigning it the tilde (`~`) value.

Setting the tags key does not automatically disable the default branches filter!

These value patterns are case insensitive. That means the characters are matched regardless of their case. The values can be specified in a comma-separated list or as single items on individual lines.

Add a default tags filter

The tags key isn’t used by default (unlike the branches key and its default filter). To apply the same tag filter to all the url entries that don’t declare the a tags key explicitly, specify a tags key directly on the content key.

Example 2. Assign a default tags filter

content:
  tags: v* (1)
  branches: ~ (2)
  sources:
  - url: https://git-service.com/org/repo-z.git (3)
  - url: https://git-service.com/org/repo-x.git
    tags: [v*, '!v1.*'] (4)
  - url: https://git-service.com/org/repo-y.git (5)

1	Specify `tags` under the `content` key to create a default tags filter.
2	Disable the default branches filter on all `url` keys.
3	This `url` will use the default tags filter.
4	The value assigned to this `tags` key will be applied to the `url` it’s specified on, overriding the default tags filter.
5	This `url` will use the default tags filter.

With the creation of the default tags filter, Antora will now discover and use tags that begin with the letter v for all content sources that don’t explicitly declare a tags key.

Use tags and branches from the same repository

In this example, we’ll load the main branch of a content repository as well as tags starting with the letter v.

content:
  sources:
  - url: https://git-service.com/org/repo-x.git
    branches: [main, sneaky-chinchilla]
    tags: v*

For an in depth look at using wildcards (*), see Wildcards. Antora also supports matching tag names using exclusions, braces, alternation, ranges, and repetition patterns. See Refname Matching in Content Sources.