Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a cumulative approach: instead of creating separate pages for each product and release, we update a single page with product- and version-specific details over time.
To support this, source files use a tagging system to indicate:
- Which Elastic products and deployment models the content applies to.
- When a feature changes state relative to the base version.
This is what the applies_to metadata is for. It can be used at the page, section, or inline level to specify applicability with precision.
:::{note} For detailed guidance, refer to Write cumulative documentation. :::
The applies_to metadata supports an exhaustive list of keys. When you write or edit documentation, only specify the keys that apply to that content.
Each key accepts values with the following syntax:
<key>: <lifecycle> [version], <lifecycle> [version], ...
Where:
- The lifecycle is mandatory.
- The version is optional.
Page level annotations are added in the YAML frontmatter, starting with the applies_to key and following the key-value reference.
All documentation pages must include an applies_to tag in the YAML frontmatter.
:::{note} In the page front matter, you should only refer to one dimension (stack/serverless, deployment, or product). Refer to the cumulative documentation guidelines for details. :::
For example:
---
applies_to:
stack: ga
---A header can be followed by an {applies_to} directive which contextualizes the applicability of the section further.
Section-level {applies_to} directives require triple backticks because their content is literal. Refer to for more information.
```{applies_to}
stack: ga 9.1
```To play even better with Markdown editors the following is also supported:
```yaml {applies_to}
stack: ga 9.1
```This allows the YAML inside the {applies_to} directive to be fully highlighted.
:::{note}
Section-level {applies_to} directives must be preceded by a heading directly.
:::
You can add inline applies annotations to any line using the following syntax:
This can live inline {applies_to}`section: <life-cycle> [version]`A specialized {preview} role exists to quickly mark something as a technical preview. It takes a required version number as an argument.
Property {preview}`<version>`
: definition bodySeveral components have built-in support for applies_to and allow to surface version information in an optimized way:
- applies-switch, a component similar to tabs but with specific support to show version badges as tab titles
- admonitions
- dropdowns
Refer to these component pages to learn about the required applies_to syntax.
Versions can be specified using several formats to indicate different applicability scenarios.
| Format | Syntax | Example | Badge Display | Description |
|---|---|---|---|---|
| Greater than or equal to (default) | x.x+ x.x x.x.x+ x.x.x |
ga 9.1 or ga 9.1+ |
9.1+ |
Applies from this version onwards |
| Range (inclusive) | x.x-y.y x.x.x-y.y.y |
preview 9.0-9.2 |
9.0-9.2 or 9.0+* |
Applies within the specified range |
| Exact version | =x.x =x.x.x |
beta =9.1 |
9.1 |
Applies only to this specific version |
* Range display depends on release status of the second version.
Important notes:
- Versions are always displayed as Major.Minor (e.g.,
9.1) in badges, regardless of whether you specify patch versions in the source. - Each version statement corresponds to the latest patch of the specified minor version (e.g.,
9.1represents 9.1.0, 9.1.1, 9.1.6, etc.). - When critical patch-level differences exist, use plain text descriptions alongside the badge rather than specifying patch versions.
- Disambiguation between
+and=:=means that the lifecycle state is valid for that version and that version only. If you're not on that version, then this content does not concern you.+means that the content is true for that version and any subsequent versions. If you're on that version, then this content does concern you.
The following table shows how different version syntaxes render:
| Rendered | Raw input | Notes |
|---|---|---|
{applies_to}stack: ga 9.1 |
{applies_to}`stack: ga 9.1` |
Implicit + (default behavior) |
{applies_to}stack: ga 9.1+ |
{applies_to}`stack: ga 9.1+` |
Explicit + |
{applies_to}stack: preview 9.0+ |
{applies_to}`stack: preview 9.0+` |
Preview with version |
{applies_to}stack: preview 9.0-9.2 |
{applies_to}`stack: preview 9.0-9.2` |
Range display when both ends are released |
{applies_to}stack: beta 9.1-9.3 |
{applies_to}`stack: beta 9.1-9.3` |
Converts to + if the end version is unreleased |
{applies_to}stack: beta =9.1 |
{applies_to}`stack: beta =9.1` |
In Beta for that version only (no + symbol) |
{applies_to}stack: deprecated =9.0, removed 9.1+ |
{applies_to}`stack: deprecated =9.0, removed 9.1+` |
Deprecated only in 9.0, then removed from 9.1 |
{applies_to}stack: ga 9.2+, beta 9.0-9.1 |
{applies_to}`stack: ga 9.2+, beta 9.0-9.1` |
Multiple lifecycles (highest priority shown) |
{applies_to}stack: ga 9.3, beta 9.1+ |
{applies_to}`stack: ga 9.3, beta 9.1+` |
Shows Beta when GA is unreleased (2+ lifecycles) |
{applies_to}serverless: ga |
{applies_to}`serverless: ga` |
No version badge for unversioned products |
The build process enforces the following validation rules:
- One version per lifecycle: Each lifecycle (GA, Preview, Beta, etc.) can only have one version declaration.
- ✅
stack: ga 9.2+, beta 9.0-9.1 - ❌
stack: ga 9.2, ga 9.3
- ✅
- One "greater than" per key: Only one lifecycle per product key can use the
+(greater than or equal to) syntax.- ✅
stack: ga 9.2+, beta 9.0-9.1 - ❌
stack: ga 9.2+, beta 9.0+:::{note} Onlyga 9.3+, removed 9.5+(with the two+) is forbidden while other equivalent notations are allowed: ga 9.3, removed 9.5corresponds to a previous version of the applies_to syntax, which we continue to support to avoid breaking changes.ga 9.3-9.4, removed 9.5+is the new encouraged notation to communicate this versioning scenario in the most explicit way possible, to ease future contributions. :::
- ✅
- Valid range order: In ranges, the first version must be less than or equal to the second version.
- ✅
stack: preview 9.0-9.2 - ❌
stack: preview 9.2-9.0
- ✅
- No version overlaps: Versions for the same key cannot overlap (ranges are inclusive).
- ✅
stack: ga 9.2+, beta 9.0-9.1 - ❌
stack: ga 9.2+, beta 9.0-9.2
- ✅
Use the following key-value reference to find the appropriate key and value for your applicability statements.
:::::{tab-set}
::::{tab-item} Keys
:::{include} /_snippets/applies_to-key.md :::
::::
::::{tab-item} Lifecycles
:::{include} /_snippets/applies_to-lifecycle.md :::
::::
::::{tab-item} Versions
:::{include} /_snippets/applies_to-version.md :::
:::: :::::
:::::{tab-set}
::::{tab-item} Page level
:::{include} _snippets/page-level-applies-examples.md :::
::::
::::{tab-item} Section level
:::{include} _snippets/section-level-applies-examples.md :::
::::
::::{tab-item} Inline level
:::{include} _snippets/inline-level-applies-examples.md :::
::::
:::::
:::::{tab-set}
::::{tab-item} Versioned products
Versioned products require a version tag to be used with the lifecycle tag:
applies_to:
stack: preview 9.1, ga 9.4:::{include} _snippets/versioned-lifecycle.md :::
::::
::::{tab-item} Unversioned products
Unversioned products use lifecycle tags without a version:
applies_to:
serverless:
elasticsearch: beta
observability: removed:::{include} _snippets/unversioned-lifecycle.md :::
::::
::::{tab-item} Multiple lifecycle states
:::{include} _snippets/multiple-lifecycle-states.md :::
::::
:::::
:::::{tab-set}
::::{tab-item} Stack
applies_to |
Result |
|---|---|
{applies_to}`stack: ` |
{applies_to}stack: |
{applies_to}`stack: preview` |
{applies_to}stack: preview |
{applies_to}`stack: preview 8.18` |
{applies_to}stack: preview 8.18 |
{applies_to}`stack: preview 9.0` |
{applies_to}stack: preview 9.0 |
{applies_to}`stack: preview 9.1` |
{applies_to}stack: preview 9.1 |
{applies_to}`stack: ga` |
{applies_to}stack: ga |
{applies_to}`stack: ga 8.18` |
{applies_to}stack: ga 8.18 |
{applies_to}`stack: ga 9.0` |
{applies_to}stack: ga 9.0 |
{applies_to}`stack: ga 9.1` |
{applies_to}stack: ga 9.1 |
{applies_to}`stack: beta` |
{applies_to}stack: beta |
{applies_to}`stack: beta 9.0` |
{applies_to}stack: beta 9.0 |
{applies_to}`stack: deprecated` |
{applies_to}stack: deprecated |
{applies_to}`stack: deprecated 9.0` |
{applies_to}stack: deprecated 9.0 |
{applies_to}`stack: removed` |
{applies_to}stack: removed |
{applies_to}`stack: removed 9.0` |
{applies_to}stack: removed 9.0 |
::::
::::{tab-item} Serverless
applies_to |
Result |
|---|---|
{applies_to}`serverless: ` |
{applies_to}serverless: |
{applies_to}`serverless: preview` |
{applies_to}serverless: preview |
{applies_to}`serverless: ga` |
{applies_to}serverless: ga |
{applies_to}`serverless: beta` |
{applies_to}serverless: beta |
{applies_to}`serverless: deprecated` |
{applies_to}serverless: deprecated |
{applies_to}`serverless: removed` |
{applies_to}serverless: removed |
::::
:::::
stack: preview 9.1+
serverless: ga
apm_agent_dotnet: ga 1.0+
apm_agent_java: beta 1.0+
edot_dotnet: preview 1.0+
edot_python:
edot_node: ga 1.0+
elasticsearch: preview 9.0+
security: removed 9.0
observability: deprecated 9.0+
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. {applies_to}stack: preview Aenean scelerisque viverra lectus nec dignissim.
- {applies_to}
elasticsearch: previewLorem ipsum dolor sit amet, consectetur adipiscing elit. - {applies_to}
observability: previewLorem ipsum dolor sit amet, consectetur adipiscing elit. - {applies_to}
security: previewLorem ipsum dolor sit amet, consectetur adipiscing elit.
The previous model is projected to the following structured YAML.
:::::{dropdown} Applies to model
---
applies_to:
stack:
deployment:
eck:
ess:
ece:
self:
serverless:
security:
elasticsearch:
observability:
product:
ecctl:
curator:
apm_agent_dotnet:
apm_agent_go:
apm_agent_java:
apm_agent_node:
apm_agent_php:
apm_agent_python:
apm_agent_ruby:
apm_agent_rum:
edot_collector:
edot_ios:
edot_android:
edot_dotnet:
edot_java:
edot_node:
edot_php:
edot_python:
edot_cf_aws:
edot_cf_azure:
---:::::
This section provides detailed rules for how badges are rendered based on lifecycle, version, and release status. Use this as a reference when you need to understand the exact rendering behavior.
applies_to badges are displayed in a consistent order regardless of how they appear in your source files:
- Stack - Elastic Stack
- Serverless - Elastic Cloud Serverless offerings
- Deployment - Deployment options (ECH, ECK, ECE, Self-managed)
- ProductApplicability - Specialized tools and agents (ECCTL, Curator, EDOT, APM Agents)
- Product (generic) - Generic product applicability
Within the ProductApplicability category, EDOT and APM Agent items are sorted alphabetically for better scanning.
:::{note} Inline applies annotations are rendered in the order they appear in the source file. :::
:::::{dropdown} No version declared (Serverless)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | – | – | {product} |
| Preview | – | – | {product}|Preview |
| Beta | – | – | {product}|Beta |
| Deprecated | – | – | {product}|Deprecated |
| Removed | – | – | {product}|Removed |
| Unavailable | – | – | {product}|Unavailable |
:::::
:::::{dropdown} No version declared (Other versioning systems)
When no version is declared, the badge does not show a version. The lifecycle name is shown only when it is not GA, or when there are multiple lifecycles (to disambiguate). GA is never shown when it is the only lifecycle — only the product name is shown (e.g. Stack).
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | – | 1 | {product} |
| GA | – | >= 2 | {product}|GA |
| Preview | – | – | {product}|Preview |
| Beta | – | – | {product}|Beta |
| Deprecated | – | – | {product}|Deprecated |
| Removed | – | – | {product}|Removed |
| Unavailable | – | – | {product}|Unavailable |
:::::
:::::{dropdown} Greater than or equal to (x.x+, x.x, x.x.x+, x.x.x)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | Released | >= 1 | {product}|x.x+ |
| Unreleased | 1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Preview | Released | >= 1 | {product}|Preview x.x+ |
| Unreleased | 1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Beta | Released | >= 1 | {product}|Beta x.x+ |
| Unreleased | 1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Deprecated | Released | >= 1 | {product}|Deprecated x.x+ |
| Unreleased | 1 | {product}|Deprecation planned |
|
| >= 2 | Use previous lifecycle | ||
| Removed | Released | >= 1 | {product}|Removed x.x |
| Unreleased | 1 | {product}|Removal planned |
|
| >= 2 | Use previous lifecycle |
:::::
:::::{dropdown} Range (x.x-y.y, x.x.x-y.y.y)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | y.y.y is released |
>= 1 | {product}|x.x-y.y |
y.y.y is not released, x.x.x is released |
>= 1 | {product}|x.x+ |
|
y.y.y is not released, x.x.x is not released |
1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Preview | y.y.y is released |
>= 1 | {product}|Preview x.x-y.y |
y.y.y is not released, x.x.x is released |
>= 1 | {product}|Preview x.x+ |
|
y.y.y is not released, x.x.x is not released |
1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Beta | y.y.y is released |
>= 1 | {product}|Beta x.x-y.y |
y.y.y is not released, x.x.x is released |
>= 1 | {product}|Beta x.x+ |
|
y.y.y is not released, x.x.x is not released |
1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Deprecated | y.y.y is released |
>= 1 | {product}|Deprecated x.x-y.y |
y.y.y is not released, x.x.x is released |
>= 1 | {product}|Deprecated x.x+ |
|
y.y.y is not released, x.x.x is not released |
>= 1 | {product}|Deprecation planned |
|
| Removed | y.y.y is released |
>= 1 | {product}|Removed x.x |
y.y.y is not released, x.x.x is released |
>= 1 | {product}|Removed x.x |
|
y.y.y is not released, x.x.x is not released |
>= 1 | {product}|Removal planned |
|
| Unavailable | y.y.y is released |
>= 1 | {product}|Unavailable X.X-Y.Y |
y.y.y is not released, x.x.x is released |
>= 1 | {product}|Unavailable X.X+ |
|
y.y.y is not released, x.x.x is not released |
>= 1 | ??? |
:::::
:::::{dropdown} Exact version (=x.x, =x.x.x)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | Released | >= 1 | {product}|X.X |
| Unreleased | 1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Preview | Released | >= 1 | {product}|Preview X.X |
| Unreleased | 1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Beta | Released | >= 1 | {product}|Beta X.X |
| Unreleased | 1 | {product}|Planned |
|
| >= 2 | Use previous lifecycle | ||
| Deprecated | Released | >= 1 | {product}|Deprecated X.X |
| Unreleased | >= 1 | {product}|Deprecation planned |
|
| Removed | Released | >= 1 | {product}|Removed X.X |
| Unreleased | >=1 | {product}|Removal planned |
|
| Unavailable | Released | >= 1 | {product}|Unavailable X.X |
| Unreleased | >= 1 | ??? |
:::::
:::::{dropdown} No version declared (Serverless)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | – | 1 | Generally available |
| Preview | – | 1 | Preview |
| Beta | – | 1 | Beta |
| Deprecated | – | 1 | Deprecated |
| Removed | – | 1 | Removed |
| Unavailable | – | 1 | Unavailable |
:::::
:::::{dropdown} No version declared (Other versioning systems)
When no version is declared, the popover shows only the lifecycle state (no base version):
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | – | 1 | Generally available |
| Preview | – | 1 | Preview |
| Beta | – | 1 | Beta |
| Deprecated | – | 1 | Deprecated |
| Removed | – | 1 | Removed |
| Unavailable | – | 1 | Unavailable |
:::::
:::::{dropdown} Greater than or equal to (x.x+, x.x, x.x.x+, x.x.x)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | Released | >= 1 | Generally available since X.X |
| Unreleased | 1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Preview | Released | >= 1 | Preview since X.X |
| Unreleased | 1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Beta | Released | >= 1 | Beta since X.X |
| Unreleased | 1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Deprecated | Released | >= 1 | Deprecated since X.X |
| Unreleased | >= 1 | Planned for deprecation |
|
| Removed | Released | >= 1 | Removed in X.X |
| Unreleased | >=1 | Planned for removal |
|
| Unavailable | Released | >= 1 | Unavailable since X.X |
| Unreleased | 1 | Unavailable |
|
| >= 2 | Do not add to availability list |
:::::
:::::{dropdown} Range (x.x-y.y, x.x.x-y.y.y)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | y.y.y is released |
>= 1 | Generally available from X.X to Y.Y |
y.y.y is not released, x.x.x is released |
>= 1 | Generally available since X.X |
|
y.y.y is not released, x.x.x is not released |
1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Preview | y.y.y is released |
>= 1 | Preview from X.X to Y.Y |
y.y.y is not released, x.x.x is released |
>= 1 | Preview since X.X |
|
y.y.y is not released, x.x.x is not released |
1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Beta | y.y.y is released |
>= 1 | Beta from X.X to Y.Y |
y.y.y is not released, x.x.x is released |
>= 1 | Beta since X.X |
|
y.y.y is not released, x.x.x is not released |
1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Deprecated | y.y.y is released |
>= 1 | Deprecated from X.X to Y.Y |
y.y.y is not released, x.x.x is released |
>= 1 | Deprecated since X.X |
|
y.y.y is not released, x.x.x is not released |
>= 1 | Planned for deprecation |
|
| Removed | y.y.y is released |
>= 1 | Removed in X.X |
y.y.y is not released, x.x.x is released |
>= 1 | Removed in X.X |
|
y.y.y is not released, x.x.x is not released |
>= 1 | Planned for removal |
|
| Unavailable | y.y.y is released |
>= 1 | Unavailable from X.X to Y.Y |
y.y.y is not released, x.x.x is released |
>= 1 | Unavailable since X.X |
|
y.y.y is not released, x.x.x is not released |
>= 1 | Do not add to availability list |
:::::
:::::{dropdown} Exact version (=x.x, =x.x.x)
| Lifecycle | Release status | Lifecycle count | Rendered output |
|---|---|---|---|
| GA | Released | >= 1 | Generally available in X.X |
| Unreleased | 1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Preview | Released | >= 1 | Preview in X.X |
| Unreleased | 1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Beta | Released | >= 1 | Beta in X.X |
| Unreleased | 1 | Planned |
|
| >= 2 | Do not add to availability list | ||
| Deprecated | Released | >= 1 | Deprecated in X.X |
| Unreleased | >= 1 | Planned for deprecation |
|
| Removed | Released | >= 1 | Removed in X.X |
| Unreleased | >=1 | Planned for removal |
|
| Unavailable | Released | >= 1 | Unavailable in X.X |
| Unreleased | >= 1 | Do not add to availability list |
:::::