---
title: versions.yml
description: The versions.yml file specifies which versions of each product should be recognized as the minimum (base) and the latest (current) in documentation builds...
url: https://docs-v3-preview.elastic.dev/docs-builder/documentation/catalog/versions
products:
  - Elastic Docs Builder
---

# versions.yml
The [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml) file specifies which versions of each product should be recognized as the minimum (base) and the latest (current) in documentation builds.
This example sets the Elastic Stack base and current versions while also assigning them to a variable that can be accessed with `*stack`
```yml
versioning_systems:
  stack: &stack
    base: 9.0
    current: 9.0.4
```

Versions set in this file are surfaced to the user via `applies_to` tags.
`applies_to` tags are rendered as badges in the documentation output. They reproduce the "key + lifecycle status + version" indicated in the content sources.
Specifically for versioned products, badges will display differently when the `applies_to` key specifies a product version that has not been released to our customers yet.
The following table shows how badges for versioned products are displayed based on the release status for each lifecycle value. Hover over the example badges for the tooltip text.

| Lifecycle  | Release status | Badge text examples                                                   |
|------------|----------------|-----------------------------------------------------------------------|
| preview    | prerelease     | <applies-to>Elastic Stack: Planned</applies-to>                       |
|            | post-release   | <applies-to>Elastic Stack: Preview since 9.1</applies-to>             |
| beta       | prerelease     | <applies-to>Elastic Stack: Planned</applies-to>                       |
|            | post-release   | <applies-to>Elastic Stack: Beta since 9.1</applies-to>                |
| ga         | prerelease     | <applies-to>Elastic Stack: Planned</applies-to>                       |
|            | post-release   | <applies-to>Elastic Stack: Generally available since 9.1</applies-to> |
| deprecated | prerelease     | <applies-to>Elastic Stack: Planned for deprecation</applies-to>       |
|            | post-release   | <applies-to>Elastic Stack: Deprecated since 9.1</applies-to>          |
| removed    | prerelease     | <applies-to>Elastic Stack: Planned for removal</applies-to>           |
|            | post-release   | <applies-to>Elastic Stack: Removed in 9.1</applies-to>                |

This is computed at build time (there is a docs build every 30 minutes). The documentation team tracks and maintains released versions for these products centrally in [`versions.yml`](https://github.com/elastic/docs-builder/blob/main/config/versions.yml).
When multiple lifecycle statuses and versions are specified in the sources, several badges are shown.
<note>
  Visuals and wording in the output documentation are subject to changes and optimizations.
</note>

See [Write cumulative documentation](https://www.elastic.co/docs/contribute-docs/how-to/cumulative-docs) for more information.

## Version substitutions

Like `products.yml` (which provides `{{product.<id>}}` substitutions), `versions.yml` exposes version numbers as substitution variables so you can reference current or next versions without hardcoding.
Use `{{version.<system> | <mutation>}}` to display version numbers. [Mutations](/docs-builder/syntax/substitutions#mutations) let you derive related versions from the current value:

| Substitution                      | Example output | Description               |
|-----------------------------------|----------------|---------------------------|
| `{{version.stack \| M.x}}`        | `9.x`          | Major with `.x` wildcard  |
| `{{version.stack \| M.M}}`        | `9.0`          | Major.minor               |
| `{{version.stack \| M}}`          | `9`            | Major only                |
| `{{version.stack \| M+1}}`        | `10`           | Next major                |
| `{{version.stack \| M+1 \| M.M}}` | `10.0`         | Next major as major.minor |
| `{{version.stack \| M.M+1}}`      | `9.1`          | Next minor                |

This is useful for documentation that references version-specific behavior without needing updates on every release:
```markdown
This feature is available in {{version.stack | M.M}} and later.
Upgrade to {{version.stack | M+1 | M.M}} for the next major release.
```

For the full list of available mutations, see [substitution mutations](/docs-builder/syntax/substitutions#mutations).