From 15988eb7918389dcff44edc1fa34df639d68793b Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Fri, 30 May 2025 13:09:18 +0200 Subject: [PATCH 01/18] Applies versioning changes to the `applies` page --- docs/syntax/applies.md | 96 +++++++++++++++++++----------------------- 1 file changed, 43 insertions(+), 53 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 5ca89b4bb..1fc31789d 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -4,18 +4,18 @@ applies_to: deployment: eck: ga 9.0 ess: beta 9.1 - ece: discontinued 9.2.0 - self: unavailable 9.3.0 + ece: deprecated 9.2.0 + self: unavailable serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 - product: planned 9.5, discontinued 9.7 + security: unavailable + elasticsearch: beta + observability: deprecated + product: preview 9.5, deprecated 9.7 --- # Applies to -Allows you to annotate a page or section's applicability. +Allows you to annotate a page or section's applicability. The documentation follows a cumulative model: changes across versions are shown on a single page. Use the `applies_to` tag to reflect a feature’s state across versions. For more on the versioning approach, see [Contribution guide](../contribute/index.md). ### Syntax @@ -25,13 +25,14 @@ Allows you to annotate a page or section's applicability. Taking a mandatory [life-cycle](#life-cycle) with an optional version. -#### Life cycle: +#### Life cycle + +Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. + * `preview` * `beta` - * `development` * `deprecated` - * `planned` - * `discontinued` + * `removed` * `unavailable` * `ga` @@ -42,29 +43,11 @@ Can be in either `major.minor` or `major.minor.patch` format #### Examples ``` -planned 9.5, discontinued 9.7 -discontinued 9.2.0 -all -``` - -`all` means generally available for all active versions - -```yaml -applies_to: - serverless: all -``` - -`all` can also be specified at a version level - -```yaml -applies_to: - stack: beta all - serverless: beta +preview 9.5, ga 9.7 +deprecated 9.9.0 +unavailable ``` -Note `all` just means we won't be rendering the version portion in the HTML. - - ## Structured model ![Applies To Model](images/applies.png) @@ -91,8 +74,14 @@ This allows you to annotate various facets as defined in [](../migration/version ## Page annotations -Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status +Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status. +``` yaml +applies_to: + product: preview 9.5 +products: + -id: cloud-kubernetes +``` ```yaml --- @@ -101,13 +90,13 @@ applies_to: deployment: eck: ga 9.0 ess: beta 9.1 - ece: discontinued 9.2.0 - self: unavailable 9.3.0 + ece: deprecated 9.2.0 + self: unavailable serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 - product: planned 9.5, discontinued 9.7 + security: unavailable + elasticsearch: beta + observability: deprecated + product: preview 9.5, deprecated 9.7 --- ``` @@ -119,13 +108,13 @@ stack: ga 9.1 deployment: eck: ga 9.0 ess: beta 9.1 - ece: discontinued 9.2.0 - self: unavailable 9.3.0 + ece: deprecated 9.2.0 + self: unavailable serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 -product: planned 9.5, discontinued 9.7 + security: unavailable + elasticsearch: beta + observability: deprecated +product: preview 9.5, deprecated 9.7 ``` A header may be followed by an `{applies_to}` directive which will contextualize the applicability @@ -181,8 +170,6 @@ Property {preview}`` : definition body ``` - - ## Examples #### Stack only @@ -202,21 +189,24 @@ deployment: #### Deployment only ```yaml {applies_to} deployment: - ece: discontinued 9.2.0 - self: unavailable 9.3.0 + ece: deprecated 9.2.0 + self: unavailable ``` #### Serverless only +When a change is released in `ga` for unversioned products, it doesn’t need any specific tagging. + ```yaml {applies_to} -serverless: ga 9.0.0 + serverless: + elasticsearch: preview ``` #### Serverless with project differences ```yaml {applies_to} serverless: - security: ga 9.0.0 - elasticsearch: beta 9.1.0 - observability: discontinued 9.2.0 + security: unavailable + elasticsearch: beta + observability: deprecated ``` #### Stack with product ```yaml {applies_to} From 7e59bab7679b66be953723b58270044284aa593e Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Fri, 30 May 2025 13:38:13 +0200 Subject: [PATCH 02/18] Add information about tagging feature lifecycle and version changes --- docs/syntax/applies.md | 52 +++++++++++++++++++++++++++++++++++++++--- 1 file changed, 49 insertions(+), 3 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 1fc31789d..d7531f584 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -74,7 +74,7 @@ This allows you to annotate various facets as defined in [](../migration/version ## Page annotations -Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status. +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status. ``` yaml applies_to: @@ -100,7 +100,6 @@ applies_to: --- ``` - ## Section annotation [#sections] ```yaml {applies_to} @@ -141,7 +140,7 @@ stack: ga 9.1 ``` ```` -This will allow the yaml inside the `{applies-to}` directive to be fully highlighted. +This will allow the yaml inside the `{applies_to}` directive to be fully highlighted. ## Inline Applies To @@ -170,6 +169,53 @@ Property {preview}`` : definition body ``` +## Tagging feature lifecycle and version changes + +Elastic documentation follows a cumulative model: a single page shows the current state of a feature across versions and deployments. To support this, **version-related changes must be tagged using the `applies_to` key**. + +Use the applies_to tag when: +* A feature is introduced (e.g., preview, beta, or ga) +* A feature is deprecated (e.g., deprecated) +* A feature is removed (e.g., removed) + +You don’t need version tagging for: +* Typos, formatting, or style changes +* Long-standing features being documented for the first time +* Content updates that don’t reflect a feature lifecycle change + +### Versioned vs. unversioned products + +Versioned products require a lifecycle tag with a version: + +``` +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 + deployment: + ess: deprecated +``` + +### Combined states +You can specify multiple lifecycle states for the same product, separated by commas. For example: + +``` +applies_to: + stack: preview 9.1, ga 9.4 +``` + +This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. + + + ## Examples #### Stack only From 2013c3b04e1351da60e9fc37857193d06890c298 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Fri, 30 May 2025 13:56:29 +0200 Subject: [PATCH 03/18] Clarify applies_to usage --- docs/syntax/applies.md | 92 +++++++++++++++++++++--------------------- 1 file changed, 45 insertions(+), 47 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index d7531f584..4893db19f 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -48,6 +48,51 @@ deprecated 9.9.0 unavailable ``` +## When to use `applies_to` + +The cumulative model used in our documentation means that a single page reflects the state of a feature across versions and deployments. To support this, **version-related changes must be tagged using the `applies_to` key**. Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. + +Use version tagging when: +* A feature is introduced (e.g., preview, beta, or ga) +* A feature is deprecated (e.g., deprecated) +* A feature is removed (e.g., removed) + +You don’t need version tagging for: +* Typos, formatting, or style changes +* Long-standing features being documented for the first time +* Content updates that don’t reflect a feature lifecycle change + +### Versioned vs. unversioned products + +Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): + +``` +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 + deployment: + ess: deprecated +``` + +### Combined states +You can specify multiple lifecycle states for the same product, separated by commas. For example: + +``` +applies_to: + stack: preview 9.1, ga 9.4 +``` + +This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. + ## Structured model ![Applies To Model](images/applies.png) @@ -169,53 +214,6 @@ Property {preview}`` : definition body ``` -## Tagging feature lifecycle and version changes - -Elastic documentation follows a cumulative model: a single page shows the current state of a feature across versions and deployments. To support this, **version-related changes must be tagged using the `applies_to` key**. - -Use the applies_to tag when: -* A feature is introduced (e.g., preview, beta, or ga) -* A feature is deprecated (e.g., deprecated) -* A feature is removed (e.g., removed) - -You don’t need version tagging for: -* Typos, formatting, or style changes -* Long-standing features being documented for the first time -* Content updates that don’t reflect a feature lifecycle change - -### Versioned vs. unversioned products - -Versioned products require a lifecycle tag with a version: - -``` -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 - deployment: - ess: deprecated -``` - -### Combined states -You can specify multiple lifecycle states for the same product, separated by commas. For example: - -``` -applies_to: - stack: preview 9.1, ga 9.4 -``` - -This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. - - - ## Examples #### Stack only From 0726a4a83c3b7898fead9213037953f03f0125a4 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Fri, 30 May 2025 14:06:33 +0200 Subject: [PATCH 04/18] Cleaning up the document --- docs/syntax/applies.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 4893db19f..99028f282 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -79,8 +79,6 @@ applies_to: serverless: elasticsearch: beta observability: removed - deployment: - ess: deprecated ``` ### Combined states @@ -119,7 +117,7 @@ This allows you to annotate various facets as defined in [](../migration/version ## Page annotations -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Using yaml frontmatter pages can explicitly indicate to each deployment targets availability and lifecycle status. +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. ``` yaml applies_to: From 768ef7d71ba9dea6b4682284db836e0c8dadce74 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Fri, 30 May 2025 14:34:42 +0200 Subject: [PATCH 05/18] Restructure life-cycles and fix typos --- docs/syntax/applies.md | 42 +++++++++++++++++++++--------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 99028f282..0a445a65b 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -40,6 +40,23 @@ Both versioned and unversioned products use the same lifecycle tags, but only ve Can be in either `major.minor` or `major.minor.patch` format +Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): + +``` +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 +``` + #### Examples ``` @@ -62,25 +79,6 @@ You don’t need version tagging for: * Long-standing features being documented for the first time * Content updates that don’t reflect a feature lifecycle change -### Versioned vs. unversioned products - -Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): - -``` -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 -``` - ### Combined states You can specify multiple lifecycle states for the same product, separated by commas. For example: @@ -120,10 +118,12 @@ This allows you to annotate various facets as defined in [](../migration/version All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. ``` yaml +--- applies_to: - product: preview 9.5 + product: preview 9.5, ga 9.6 products: - -id: cloud-kubernetes + - id: cloud-kubernetes +--- ``` ```yaml From 83a0f605e78062f062ec13e0313c1e75f2f4eac6 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Fri, 30 May 2025 16:55:38 +0200 Subject: [PATCH 06/18] Update docs/syntax/applies.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/syntax/applies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 0a445a65b..c8d10b5f6 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -15,7 +15,7 @@ applies_to: # Applies to -Allows you to annotate a page or section's applicability. The documentation follows a cumulative model: changes across versions are shown on a single page. Use the `applies_to` tag to reflect a feature’s state across versions. For more on the versioning approach, see [Contribution guide](../contribute/index.md). +The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. ### Syntax From cd3e03e6c0e48b7cacfa6bcebccf9593255d823e Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Fri, 30 May 2025 16:56:59 +0200 Subject: [PATCH 07/18] Update docs/syntax/applies.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/syntax/applies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index c8d10b5f6..6d35496bb 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -67,7 +67,7 @@ unavailable ## When to use `applies_to` -The cumulative model used in our documentation means that a single page reflects the state of a feature across versions and deployments. To support this, **version-related changes must be tagged using the `applies_to` key**. Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. +Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. Use version tagging when: * A feature is introduced (e.g., preview, beta, or ga) From b4c261c6b49d6b04dc6f21ea271fb5405cca2226 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Mon, 2 Jun 2025 08:12:58 +0200 Subject: [PATCH 08/18] Apply review requests --- docs/syntax/applies.md | 68 +++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 41 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 6d35496bb..d0703ba21 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,23 +1,22 @@ ---- -applies_to: - stack: ga 9.1 - deployment: - eck: ga 9.0 - ess: beta 9.1 - ece: deprecated 9.2.0 - self: unavailable - serverless: - security: unavailable - elasticsearch: beta - observability: deprecated - product: preview 9.5, deprecated 9.7 ---- - # Applies to The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. -### Syntax +## When to use `applies_to` + +Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. + +Use version tagging when: +* A feature is introduced (e.g., preview, beta, or ga) +* A feature is deprecated (e.g., deprecated) +* A feature is removed (e.g., removed) + +You don’t need version tagging for: +* Typos, formatting, or style changes +* Long-standing features being documented for the first time +* Content updates that don’t reflect a feature lifecycle change + +## Syntax ``` [version], [version] @@ -25,9 +24,18 @@ The `applies_to` metadata allows you to specify which product versions, deployme Taking a mandatory [life-cycle](#life-cycle) with an optional version. +### Combined states +You can specify multiple lifecycle states for the same product, separated by commas. For example: + +``` +applies_to: + stack: preview 9.1, ga 9.4 +``` +This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. + #### Life cycle -Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. +`applies_to` accepts the following lifecycle states: * `preview` * `beta` @@ -36,6 +44,8 @@ Both versioned and unversioned products use the same lifecycle tags, but only ve * `unavailable` * `ga` +Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. + #### Version Can be in either `major.minor` or `major.minor.patch` format @@ -65,30 +75,6 @@ deprecated 9.9.0 unavailable ``` -## When to use `applies_to` - -Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. - -Use version tagging when: -* A feature is introduced (e.g., preview, beta, or ga) -* A feature is deprecated (e.g., deprecated) -* A feature is removed (e.g., removed) - -You don’t need version tagging for: -* Typos, formatting, or style changes -* Long-standing features being documented for the first time -* Content updates that don’t reflect a feature lifecycle change - -### Combined states -You can specify multiple lifecycle states for the same product, separated by commas. For example: - -``` -applies_to: - stack: preview 9.1, ga 9.4 -``` - -This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. - ## Structured model ![Applies To Model](images/applies.png) From 05e9176b4d8dc46671163fba1f619edeb251e32e Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Mon, 2 Jun 2025 08:59:21 +0200 Subject: [PATCH 09/18] Restructure content --- docs/syntax/applies.md | 129 +++++++++++++++++++++-------------------- 1 file changed, 65 insertions(+), 64 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index d0703ba21..33210d16e 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -2,27 +2,34 @@ The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. -## When to use `applies_to` +## Syntax -Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. +``` + [version], [version] +``` -Use version tagging when: -* A feature is introduced (e.g., preview, beta, or ga) -* A feature is deprecated (e.g., deprecated) -* A feature is removed (e.g., removed) +Taking a mandatory [life-cycle](#life-cycle) with an optional version. -You don’t need version tagging for: -* Typos, formatting, or style changes -* Long-standing features being documented for the first time -* Content updates that don’t reflect a feature lifecycle change +### Version -## Syntax +Can be in either `major.minor` or `major.minor.patch` format + +Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): ``` - [version], [version] +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: -Taking a mandatory [life-cycle](#life-cycle) with an optional version. +``` +applies_to: + serverless: + elasticsearch: beta + observability: removed +``` ### Combined states You can specify multiple lifecycle states for the same product, separated by commas. For example: @@ -33,7 +40,7 @@ applies_to: ``` This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. -#### Life cycle +### Life cycle `applies_to` accepts the following lifecycle states: @@ -46,60 +53,31 @@ This shows that the feature was introduced in version 9.1 as a preview and becam Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. -#### Version - -Can be in either `major.minor` or `major.minor.patch` format - -Versioned products require a `version` tag to be used with the `lifecycle` tag. See [Syntax](#syntax): - -``` -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: +## When and where to use `applies_to` -``` -applies_to: - serverless: - elasticsearch: beta - observability: removed -``` +The `applies_to` tag can be added at different levels in the documentation: [page-level](#page-annotations), [section-level](#section-annotations), and [inline](#inline-applies-to). Each level uses slightly different syntax and serves a specific purpose: +* [Page-level](#page-annotations) tagging is **mandatory** and must be included in the frontmatter. It defines the overall applicability of the page across products, deployments, and environments. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). -#### Examples +When the context differs from what was specified at the page level in a specific section or part of the page, it is appropriate to re-establish it. -``` -preview 9.5, ga 9.7 -deprecated 9.9.0 -unavailable -``` +* [Section-level](#section-annotations) annotation lets you show or hide specific sections of content depending on the target context. This is helpful when only a part of a page varies between products or versions. +* [Inline tagging](#inline-applies-to) allows fine-grained annotations within paragraphs or definition lists. It’s useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. -## Structured model +### When to use `applies_to` -![Applies To Model](images/applies.png) +Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. -The above model is projected to the following structured yaml. +Use version tagging when: +* A feature is introduced (e.g., preview, beta, or ga) +* A feature is deprecated (e.g., deprecated) +* A feature is removed (e.g., removed) -```yaml ---- -applies_to: - stack: - deployment: - eck: - ess: - ece: - self: - serverless: - security: - elasticsearch: - observability: - product: ---- -``` -This allows you to annotate various facets as defined in [](../migration/versioning.md) +You don’t need version tagging for: +* Typos, formatting, or style changes +* Long-standing features being documented for the first time +* Content updates that don’t reflect a feature lifecycle change -## Page annotations +### Page annotations All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. @@ -129,7 +107,7 @@ applies_to: --- ``` -## Section annotation [#sections] +### Section annotations ```yaml {applies_to} stack: ga 9.1 @@ -171,7 +149,7 @@ stack: ga 9.1 This will allow the yaml inside the `{applies_to}` directive to be fully highlighted. -## Inline Applies To +### Inline Applies To Inline applies to can be placed anywhere using the following syntax @@ -198,6 +176,30 @@ Property {preview}`` : definition body ``` +## Structured model + +![Applies To Model](images/applies.png) + +The above model is projected to the following structured yaml. + +```yaml +--- +applies_to: + stack: + deployment: + eck: + ess: + ece: + self: + serverless: + security: + elasticsearch: + observability: + product: +--- +``` +This allows you to annotate various facets as defined in [](../migration/versioning.md) + ## Examples #### Stack only @@ -205,7 +207,6 @@ Property {preview}`` stack: ga 9.1 ``` - #### Stack with deployment ```yaml {applies_to} stack: ga 9.1 @@ -239,4 +240,4 @@ serverless: #### Stack with product ```yaml {applies_to} stack: ga 9.1 -``` +``` \ No newline at end of file From b23d2cc15a0d792f6e30e37a7ad352d07b8372bc Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Mon, 2 Jun 2025 15:06:32 +0200 Subject: [PATCH 10/18] Update docs/syntax/applies.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/syntax/applies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 33210d16e..537961556 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -149,7 +149,7 @@ stack: ga 9.1 This will allow the yaml inside the `{applies_to}` directive to be fully highlighted. -### Inline Applies To +### Inline annotations Inline applies to can be placed anywhere using the following syntax From 6a2ab7db5794c0bc2f368388062ba6ef311e6b34 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Mon, 2 Jun 2025 15:08:59 +0200 Subject: [PATCH 11/18] Update docs/syntax/applies.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/syntax/applies.md | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 537961556..eb5658be5 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -55,27 +55,15 @@ Both versioned and unversioned products use the same lifecycle tags, but only ve ## When and where to use `applies_to` -The `applies_to` tag can be added at different levels in the documentation: [page-level](#page-annotations), [section-level](#section-annotations), and [inline](#inline-applies-to). Each level uses slightly different syntax and serves a specific purpose: -* [Page-level](#page-annotations) tagging is **mandatory** and must be included in the frontmatter. It defines the overall applicability of the page across products, deployments, and environments. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). +✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. -When the context differs from what was specified at the page level in a specific section or part of the page, it is appropriate to re-establish it. +❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. -* [Section-level](#section-annotations) annotation lets you show or hide specific sections of content depending on the target context. This is helpful when only a part of a page varies between products or versions. -* [Inline tagging](#inline-applies-to) allows fine-grained annotations within paragraphs or definition lists. It’s useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. +The `applies_to` metadata can be added at different levels in the documentation: -### When to use `applies_to` - -Every page must include a [page-level `applies_to`](#page-annotations) tag to clearly define its scope and availability. - -Use version tagging when: -* A feature is introduced (e.g., preview, beta, or ga) -* A feature is deprecated (e.g., deprecated) -* A feature is removed (e.g., removed) - -You don’t need version tagging for: -* Typos, formatting, or style changes -* Long-standing features being documented for the first time -* Content updates that don’t reflect a feature lifecycle change +* [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments. +* [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. +* [Inline](#inline-applies-to) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. ### Page annotations From b67e2cf91f975a22c6934279956dda50418036d1 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Mon, 2 Jun 2025 15:09:14 +0200 Subject: [PATCH 12/18] Update docs/syntax/applies.md Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/syntax/applies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index eb5658be5..4be8d1d57 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -67,7 +67,7 @@ The `applies_to` metadata can be added at different levels in the documentation: ### Page annotations -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). ``` yaml --- From ef7095315d3ad0610bb3e0231ca70737f68727fe Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Mon, 2 Jun 2025 15:17:12 +0200 Subject: [PATCH 13/18] Fix broken links and move `life cycle` section --- docs/syntax/applies.md | 28 ++++++++++++++-------------- docs/syntax/quick-ref.md | 2 +- docs/versions/content-patterns.md | 2 +- 3 files changed, 16 insertions(+), 16 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 4be8d1d57..c0e44238e 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -10,6 +10,19 @@ The `applies_to` metadata allows you to specify which product versions, deployme Taking a mandatory [life-cycle](#life-cycle) with an optional version. +### Life cycle + +`applies_to` accepts the following lifecycle states: + + * `preview` + * `beta` + * `deprecated` + * `removed` + * `unavailable` + * `ga` + +Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. + ### Version Can be in either `major.minor` or `major.minor.patch` format @@ -40,19 +53,6 @@ applies_to: ``` This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. -### Life cycle - -`applies_to` accepts the following lifecycle states: - - * `preview` - * `beta` - * `deprecated` - * `removed` - * `unavailable` - * `ga` - -Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. - ## When and where to use `applies_to` ✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. @@ -63,7 +63,7 @@ The `applies_to` metadata can be added at different levels in the documentation: * [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments. * [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. -* [Inline](#inline-applies-to) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. +* [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. ### Page annotations diff --git a/docs/syntax/quick-ref.md b/docs/syntax/quick-ref.md index c7d280db7..445c719ae 100644 --- a/docs/syntax/quick-ref.md +++ b/docs/syntax/quick-ref.md @@ -146,7 +146,7 @@ The `applies_to` tags are scope signals for readers, not comprehensive metadata. **DOs**
✅ **Do:** Define a set of [page-level tags](applies.md#page-annotations) in a front matter block
-✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#sections) after a heading
+✅ **Do:** Add section-level tags in an `{applies_to}` [directive](applies.md#section-annotations) after a heading
✅ **Do:** Indicate versions (`major.minor` with an optional `[.patch]`) and release phases like `beta` **DON'Ts**
diff --git a/docs/versions/content-patterns.md b/docs/versions/content-patterns.md index a68b931e3..e914bf3d9 100644 --- a/docs/versions/content-patterns.md +++ b/docs/versions/content-patterns.md @@ -39,7 +39,7 @@ deployment: self: unavailable 9.3.0 ``` -*see [`applies`](/syntax/applies.md#sections)* +*see [`applies`](/syntax/applies.md#section-annotations)* **Use case:** Provide signals about a section’s scope so a user can choose to read or skip it as needed From 3ac792a3d0e993b14a4975ab29726fba28ae2047 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Wed, 4 Jun 2025 13:58:10 +0200 Subject: [PATCH 14/18] Replace/add applies_to examples --- docs/syntax/applies.md | 266 +++++++++++++++++++++++++++++------------ 1 file changed, 187 insertions(+), 79 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index c0e44238e..892f57f59 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -44,15 +44,6 @@ applies_to: observability: removed ``` -### Combined states -You can specify multiple lifecycle states for the same product, separated by commas. For example: - -``` -applies_to: - stack: preview 9.1, ga 9.4 -``` -This shows that the feature was introduced in version 9.1 as a preview and became generally available in 9.4. - ## When and where to use `applies_to` ✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. @@ -65,36 +56,142 @@ The `applies_to` metadata can be added at different levels in the documentation: * [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. * [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. -### Page annotations - -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). +### Lifecycle examples + +#### Unversioned products +Unversioned products aren’t following 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 + +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: -``` yaml ---- -applies_to: - product: preview 9.5, ga 9.6 -products: - - id: cloud-kubernetes ---- ``` - -```yaml --- applies_to: - stack: ga 9.1 deployment: - eck: ga 9.0 - ess: beta 9.1 - ece: deprecated 9.2.0 - self: unavailable - serverless: - security: unavailable - elasticsearch: beta - observability: deprecated - product: preview 9.5, deprecated 9.7 + ece: deprecated 4.0, removed 4.8 + ess: removed --- ``` +### Page annotations + +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). + +#### Page annotation examples + +There are 3 typical scenarios to start from: +1. The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI: + + ```yaml + --- + applies_to: + stack: ga + serverless: ga + products: + -id: kibana + -id: elasticsearch + -id: elastic-stack + --- + ``` + +2. The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys): + + ```yaml + --- + applies_to: + serverless: ga + deployment: + ess: ga + ece: ga + eck: ga + products: + -id: cloud-serverless + -id: cloud-hosted + -id: cloud-enterprise + -id: cloud-kubernetes + --- + ``` + +3. The documentation set or page is primarily about a product following its own versioning schema: + + ```yaml + --- + applies_to: + product: ga + products: + -id: edot-collector + --- + ``` + ### Section annotations ```yaml {applies_to} @@ -137,6 +234,57 @@ stack: ga 9.1 This will allow the yaml inside the `{applies_to}` directive to be fully highlighted. +#### Section annotation examples + +1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative for it): + + ````markdown + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + +2. The whole page is generally applicable to Elastic Cloud Enterprise and Elastic Cloud Hosted, but one specific paragraph only applies to Elastic Cloud Enterprise, and another paragraph explains the same, but for Elastic Cloud Hosted: + + ````markdown + ## Secure a deployment [secure-deployment-ech] + ```{applies_to} + deployment: + ess: ga + ``` + + [...] + + ## Secure a deployment [secure-deployment-ece] + ```{applies_to} + deployment: + ece: ga + ``` + + [...] + ```` +3. A specific section, paragraph or list item has specific applicability that differs from the context set at the page or section level, and the action is not possible at all for that context (meaning that there is no alternative). For example: + + ````markdown + --- + applies_to: + stack: ga + serverless: ga + --- + + # Spaces + + [...] + + ## Configure a space-level landing page [space-landing-page] + ```{applies_to} + stack: ga + serverless: unavailable + ``` + ```` + ### Inline annotations Inline applies to can be placed anywhere using the following syntax @@ -147,14 +295,16 @@ This can live inline {applies_to}`section: [version]` An inline version example would be {applies_to}`stack: beta 9.1` this allows you to target elements more concretely visually. -A common use case would be to place them on definition lists: +#### Inline annotation examples -Fruit {applies_to}`stack: preview 9.1` -: A sweet and fleshy product of a tree or other plant that contains seed and can be eaten as food. Common examples include apples, oranges, and bananas. Most fruits are rich in vitamins, minerals and fiber. +1. The whole page is generally applicable to Elastic Stack 9.0 and to Serverless, but one specific section isn’t applicable to Serverless (and there is no alternative): -Applies {preview}`9.1` -: A sweet and fleshy product of a tree or other plant that contains seed and can be eaten as food. Common examples include apples, oranges, and bananas. Most fruits are rich in vitamins, minerals and fiber. + ````markdown + **Spaces** let you organize your content and users according to your needs. + - Each space has its own saved objects. + - {applies_to}`stack: ga` {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view. + ```` A specialized `{preview}` role exist to quickly mark something as a technical preview. It takes a required version number as argument. @@ -186,46 +336,4 @@ applies_to: product: --- ``` -This allows you to annotate various facets as defined in [](../migration/versioning.md) - -## Examples - -#### Stack only -```yaml {applies_to} -stack: ga 9.1 -``` - -#### Stack with deployment -```yaml {applies_to} -stack: ga 9.1 -deployment: - eck: ga 9.0 - ess: beta 9.1 -``` - -#### Deployment only -```yaml {applies_to} -deployment: - ece: deprecated 9.2.0 - self: unavailable -``` - -#### Serverless only -When a change is released in `ga` for unversioned products, it doesn’t need any specific tagging. - -```yaml {applies_to} - serverless: - elasticsearch: preview -``` - -#### Serverless with project differences -```yaml {applies_to} -serverless: - security: unavailable - elasticsearch: beta - observability: deprecated -``` -#### Stack with product -```yaml {applies_to} -stack: ga 9.1 -``` \ No newline at end of file +This allows you to annotate various facets as defined in [](../migration/versioning.md) \ No newline at end of file From 80810d6cb09a4ed2851f4cd951fc910040198a2b Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik <116336412+charlotte-hoblik@users.noreply.github.com> Date: Fri, 13 Jun 2025 18:19:36 +0200 Subject: [PATCH 15/18] Update docs/syntax/applies.md Co-authored-by: florent-leborgne --- docs/syntax/applies.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 892f57f59..7b58307e7 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -8,7 +8,7 @@ The `applies_to` metadata allows you to specify which product versions, deployme [version], [version] ``` -Taking a mandatory [life-cycle](#life-cycle) with an optional version. +Taking a mandatory [life-cycle](#life-cycle) with an optional [version](#version). ### Life cycle From b60d99718d1f373d37ed857c1055a01b66b75bf2 Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Mon, 16 Jun 2025 10:56:55 +0200 Subject: [PATCH 16/18] Apply review suggestion --- docs/syntax/applies.md | 46 +++++++++++++++++++++++++++++------------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 7b58307e7..1099561ef 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,6 +1,36 @@ # Applies to -The `applies_to` metadata allows you to specify which product versions, deployment types, and environments a specific page, section, or line applies to. Documentation published using Elastic Docs V3 follows a [cumulative model](../contribute/index.md) where a single page covers multiple versions cumulatively over time, instead of creating separate pages for each minor release. +Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/index.md): 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. + +## When and where to use `applies_to` + +The `applies_to` metadata can be added at different levels in the documentation: + +* [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments. +* [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. +* [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. + +### Do’s and don’ts + +✅ Use `applies_to` tags when features change state (`preview`, `beta`, `ga`, `deprecated`, `removed`) or when availability differs across deployments and environments. + +✅ Use `applies_to` tags to indicate which product or deployment type the content applies to. This is mandatory for every page. + +✅ Use applies_to tags when features change state in a specific update or release. + +❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. + +❌ You don’t need to tag every section or paragraph. Only do so if the context or applicability changes from what has been established earlier. + +❌ If the product is not versioned (meaning all users are always on the latest version, like in serverless or cloud), you do not need to tag a new GA feature. + +❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. ## Syntax @@ -21,8 +51,6 @@ Taking a mandatory [life-cycle](#life-cycle) with an optional [version](#version * `unavailable` * `ga` -Both versioned and unversioned products use the same lifecycle tags, but only versioned products can be marked `ga`. Unversioned products are considered `ga` by default and don’t need specification. - ### Version Can be in either `major.minor` or `major.minor.patch` format @@ -44,17 +72,7 @@ applies_to: observability: removed ``` -## When and where to use `applies_to` - -✅ Use `applies_to` tags when features change state (`introduced`, `deprecated`, `removed`) or when availability differs across deployments and environments. - -❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. - -The `applies_to` metadata can be added at different levels in the documentation: - -* [Page-level](#page-annotations) metadata is **mandatory** and must be included in the frontmatter. This defines the overall applicability of the page across products, deployments, and environments. -* [Section-level](#section-annotations) annotations allow you to specify different applicability for individual sections when only part of a page varies between products or versions. -* [Inline](#inline-annotations) annotations allow fine-grained annotations within paragraphs or definition lists. This is useful for highlighting the applicability of specific phrases, sentences, or properties without disrupting the surrounding content. +## Examples ### Lifecycle examples From baf3a86125fce061e9335b5c106232bffe48c49a Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Mon, 16 Jun 2025 11:09:01 +0200 Subject: [PATCH 17/18] Fix typos --- docs/syntax/applies.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 1099561ef..c2d0b6a1d 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -3,8 +3,8 @@ Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/index.md): 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. +* 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. @@ -22,7 +22,7 @@ The `applies_to` metadata can be added at different levels in the documentation: ✅ Use `applies_to` tags to indicate which product or deployment type the content applies to. This is mandatory for every page. -✅ Use applies_to tags when features change state in a specific update or release. +✅ Use `applies_to` tags when features change state in a specific update or release. ❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. @@ -30,8 +30,6 @@ The `applies_to` metadata can be added at different levels in the documentation: ❌ If the product is not versioned (meaning all users are always on the latest version, like in serverless or cloud), you do not need to tag a new GA feature. -❌ Don't tag content-only changes like typos, formatting, or documentation updates that don't reflect feature lifecycle changes. - ## Syntax ``` @@ -77,7 +75,7 @@ applies_to: ### Lifecycle examples #### Unversioned products -Unversioned products aren’t following a fixed versioning scheme and are released a lot more often than versioned products. All users are using the same version of this product. +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`: @@ -87,7 +85,7 @@ Unversioned products aren’t following a fixed versioning scheme and are releas serverless: preview --- ``` -* When a change introduces a deprecation, use deprecated as value for the corresponding key within the applies_to: +* When a change introduces a deprecation, use deprecated as value for the corresponding key within the `applies_to`: ``` --- @@ -162,7 +160,7 @@ applies_to: ### Page annotations -All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use yaml frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). +All documentation pages **must** include an `applies_to` tag in the YAML frontmatter. Use YAML frontmatter to indicate each deployment targets availability and lifecycle status. For a complete list of supported keys and values, see the [frontmatter syntax guide](./frontmatter.md). #### Page annotation examples @@ -234,7 +232,7 @@ the `{applies_to}` directive **MUST** be preceded by a heading directly. ::: -Note that this directive needs triple backticks since its content is literal. See also [](index.md#literal-directives) +Note that this directive requires triple backticks since its content is literal. See also [](index.md#literal-directives) ````markdown ```{applies_to} @@ -250,7 +248,7 @@ stack: ga 9.1 ``` ```` -This will allow the yaml inside the `{applies_to}` directive to be fully highlighted. +This will allow the YAML inside the `{applies_to}` directive to be fully highlighted. #### Section annotation examples @@ -336,7 +334,7 @@ Property {preview}`` ![Applies To Model](images/applies.png) -The above model is projected to the following structured yaml. +The above model is projected to the following structured YAML. ```yaml --- From 7f5c6a3adf66a5ef0129e02cd6254a956bd9ea1d Mon Sep 17 00:00:00 2001 From: Charlotte Hoblik Date: Tue, 17 Jun 2025 08:41:07 +0200 Subject: [PATCH 18/18] Fix broken links --- docs/contribute/index.md | 2 +- docs/syntax/applies.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/contribute/index.md b/docs/contribute/index.md index 61076f1ac..8ee3a794d 100644 --- a/docs/contribute/index.md +++ b/docs/contribute/index.md @@ -45,7 +45,7 @@ This [tagging system](#applies-to) is mandatory for all of the public-facing doc Use the [`applies_to`](../syntax/applies.md) tag to indicate which versions, deployment types, or release stages each part of the content is relevant to. -You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#sections) or [inline](../syntax/applies.md#inline-applies-to) level if certain parts of the content apply only to specific versions, deployment types, or release stages. +You must always use the `applies_to` tag at the [page](../syntax/applies.md#page-annotations) level. Optionally, you can also use it at the [section](../syntax/applies.md#section-annotations) or [inline](../syntax/applies.md#inline-annotations) level if certain parts of the content apply only to specific versions, deployment types, or release stages. ## Report a bug diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index c2d0b6a1d..731b0bf26 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,6 +1,6 @@ # Applies to -Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/index.md): instead of creating separate pages for each product and release, we update a single page with product- and version-specific details over time. +Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](../contribute/index.md#cumulative-docs): 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.