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.