docs-builder
Loading

Applies to

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

Page level annotations are added in the YAML frontmatter, starting with the applies_to key and following the key-value reference. For example:

---
applies_to:
  stack: ga
  deployment:
    ece: ga
---

For more examples, refer to Page annotation examples.

Important

All documentation pages must include an applies_to tag in the YAML frontmatter.

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 Syntax guide > Literal directives 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.

For more examples, refer to Section annotation examples.

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 body

For more examples, refer to Inline annotation examples.

Use the following key-value reference to find the appropriate key and value for your applicability statements.

applies_to accepts the following keys in this structure.

Note

The product key and its subkeys are used to indicate feature availability and applicability. The similarly named products frontmatter field is used to drive elastic.co search filters.

applies_to accepts the following lifecycle states:

  • preview
  • beta
  • ga
  • deprecated
  • removed
  • unavailable

applies_to accepts the following version formats:

  • Major.Minor
  • Major.Minor.Patch

Regardless of the version format used in the source file, the version number is always rendered in the Major.Minor.Patch format.

Note

Automatic Version Sorting: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6 will be displayed as stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6. Items without versions (like ga without a version or all) are sorted last.

Versioned products require a version tag to be used with the lifecycle tag:

applies_to:
  stack: preview 9.1, ga 9.4
  deployment:
    ece: deprecated 9.2, removed 9.8

Unversioned products use lifecycle tags without a version:

applies_to:
  serverless:
    elasticsearch: beta
    observability: removed
Unversioned products

Unversioned products don't follow a fixed versioning scheme and are released a lot more often than versioned products. All users are using the same version of this product.

  • When a change is released in ga, it doesn’t need any specific tagging.

  • When a change is introduced as preview or beta, use preview or beta as value for the corresponding key within the applies_to:

    ---
applies_to:
  serverless: preview
---

  • When a change introduces a deprecation, use deprecated as value for the corresponding key within the applies_to:

    ---
applies_to:
  deployment:
    ess: deprecated
---

  • When a change removes a feature, remove the content.

    Exception: If the content also applies to another context (for example a feature is removed in both Kibana 9.x and Serverless), then it must be kept for any user reading the page that may be using a version of Kibana prior to the removal.

    For example:

    ---
applies_to:
  stack: deprecated 9.1, removed 9.4
  serverless: removed
---
Versioned products

  • When a change is released in ga, users need to know which version the feature became available in:

    ---
applies_to:
  stack: ga 9.3
---

  • When a change is introduced as preview or beta, use preview or beta as value for the corresponding key within the applies_to:

    ---
applies_to:
  stack: beta 9.1
---

  • When a change introduces a deprecation, use deprecated as value for the corresponding key within the applies_to:

    ---
applies_to:
  deployment:
    ece: deprecated 4.2
---

  • When a change removes a feature, any user reading the page that may be using a version of Kibana prior to the removal must be aware that the feature is still available to them. For that reason, we do not remove the content, and instead mark the feature as removed:

    ---
applies_to:
  stack: deprecated 9.1, removed 9.4
---
Identify multiple states for the same content

applies_to keys accept comma-separated values to specify lifecycle states for multiple product versions. For example:

  • A feature is added in 9.1 as tech preview and becomes GA in 9.4:

    applies_to:
  stack: preview 9.1, ga 9.4

  • A feature is deprecated in ECE 4.0 and is removed in 4.8. At the same time, it has already been removed in Elastic Cloud Hosted:

    applies_to:
  deployment:
    ece: deprecated 4.0, removed 4.8
    ess: removed

Page annotation examples

Document is primarily about using or interacting with Elastic Stack components or the Serverless UI 
---
applies_to:
  stack: ga
  serverless: ga
---
Document is primarily about orchestrating, deploying or configuring an installation 
---
applies_to:
  serverless: ga
  deployment:
    ess: ga
    ece: ga
    eck: ga
---
Document is primarily about a product following its own versioning schema 
---
applies_to:
  edot_ios: ga
---
Applicable to Stack and Serverless, minus a section 
---
applies_to:
stack: ga
serverless: ga
---

# Spaces

[...]

#### Configure a space-level landing page [space-landing-page]
```{applies_to}
serverless: unavailable
```
Applicable to all deployment types, but some paragraphs are specific to other deployment types 
#### Cloud organization level security [cloud-organization-level]
```{applies_to}
serverless: ga
deployment:
  ess: ga
```

[...]

#### Orchestrator level security [orchestrator-level]
```{applies_to}
deployment:
  ece: ga
```

[...]
Basic example

Spaces let you organize your content and users according to your needs.

  • Each space has its own saved objects.
  • Serverless Unavailable Each space has its own navigation, called solution view.
**Spaces** let you organize your content and users according to your needs.

- Each space has its own saved objects.
- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view.
Product-specific applicability with version information

This example shows how to use directly a key from the second level of the applies_to data structure, like edot_python:.

  • EDOT Python Preview 1.7.0
  • APM Agent Java Beta 1.0.0 
- {applies_to}`edot_python: preview 1.7.0`
- {applies_to}`apm_agent_java: beta 1.0.0`
Multiple products and states in a single inline statement
  • Serverless Stack 9.1.0
  • EDOT Python GA planned EDOT Python Preview 1.7.0 APM Agent Java 1.2.0 APM Agent Java Beta 1.0.0
  • Stack 9.0.0 ECK 3.0.0 
- {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0`
- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0`
- {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0`

Applies To Model

The previous model is projected to the following structured YAML.

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:
---
Block examples

Stack Preview 9.1.0 Serverless Elasticsearch Preview 9.0.0 Serverless Observability Deprecated 9.0.0 Serverless Security Removed 9.0.0 EDOT .NET Preview 1.0.0 EDOT Node.js 1.0.0 EDOT Python APM Agent .NET 1.0.0 APM Agent Java Beta 1.0.0

In text

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. Stack Preview Aenean scelerisque viverra lectus nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictum.

  • Serverless Elasticsearch Preview Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc.
  • Serverless Observability Preview Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam.
  • Serverless Security Preview Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas ut libero diam. Mauris sed eleifend erat, sit amet auctor odio. Donec ac placerat nunc. Aenean scelerisque viverra lectus nec dignissim.
Stack
applies_to result
{applies_to}`stack: ` Stack
{applies_to}`stack: preview` Stack Preview
{applies_to}`stack: preview 8.18` Stack Preview 8.18.0
{applies_to}`stack: preview 9.0` Stack Preview 9.0.0
{applies_to}`stack: preview 9.1` Stack Preview 9.1.0
{applies_to}`stack: preview 99.0` Stack Planned
{applies_to}`stack: ga` Stack
{applies_to}`stack: ga 8.18` Stack 8.18.0
{applies_to}`stack: ga 9.0` Stack 9.0.0
{applies_to}`stack: ga 9.1` Stack 9.1.0
{applies_to}`stack: ga 99.0` Stack Planned
{applies_to}`stack: beta` Stack Beta
{applies_to}`stack: beta 8.18` Stack Beta 8.18.0
{applies_to}`stack: beta 9.0` Stack Beta 9.0.0
{applies_to}`stack: beta 9.1` Stack Beta 9.1.0
{applies_to}`stack: beta 99.0` Stack Planned
{applies_to}`stack: deprecated` Stack Deprecated
{applies_to}`stack: deprecated 8.18` Stack Deprecated 8.18.0
{applies_to}`stack: deprecated 9.0` Stack Deprecated 9.0.0
{applies_to}`stack: deprecated 9.1` Stack Deprecated 9.1.0
{applies_to}`stack: deprecated 99.0` Stack Deprecation planned
{applies_to}`stack: removed` Stack Removed
{applies_to}`stack: removed 8.18` Stack Removed 8.18.0
{applies_to}`stack: removed 9.0` Stack Removed 9.0.0
{applies_to}`stack: removed 9.1` Stack Removed 9.1.0
{applies_to}`stack: removed 99.0` Stack Removal planned
Serverless
applies_to result
{applies_to}`serverless: ` Serverless
{applies_to}`serverless: preview` Serverless Preview
{applies_to}`serverless: ga` Serverless
{applies_to}`serverless: beta` Serverless Beta
{applies_to}`serverless: deprecated` Serverless Deprecated
{applies_to}`serverless: removed` Serverless Removed

applies_to badges are displayed in a consistent order regardless of how they appear in your source files. This ensures users always see badges in a predictable hierarchy:

  1. Stack - Elastic Stack
  2. Serverless - Elastic Cloud Serverless offerings
  3. Deployment - Deployment options (ECH, ECK, ECE, Self-Managed)
  4. ProductApplicability - Specialized tools and agents (ECCTL, Curator, EDOT, APM Agents)
  5. 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.