From 1fb8889024bead73a85e85098811ca24054f1865 Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 5 Jun 2026 13:49:39 +0200 Subject: [PATCH 1/2] Add quick reference to applies_to syntax page Simplify the intro, add a quick-reference table so docs contributors can match their situation to the right annotation type, and link to the applies-to-tagging skill. Co-Authored-By: Claude Opus 4.6 --- docs/syntax/applies.md | 28 ++++++++++++++++++++-------- 1 file changed, 20 insertions(+), 8 deletions(-) diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index e5c4120f0..9c33efcee 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -1,17 +1,29 @@ # Applies to -Starting with Elastic Stack 9.0, ECE 4.0, and ECK 3.0, documentation follows a [cumulative approach](https://www.elastic.co/docs/contribute-docs/how-to/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. +Elastic documentation on [elastic.co/docs](https://www.elastic.co/docs) follows a [cumulative](https://www.elastic.co/docs/contribute-docs/how-to/cumulative-docs) model. We don't maintain versioned branches or separate copies of a page for each release. Instead, every page covers all supported versions, and writers use `applies_to` metadata to tag content with the versions, products, deployment models, and lifecycle states it applies to. -To support this, source files use a tagging system to indicate: +:::{tip} +You can use the [applies-to-tagging](https://github.com/elastic/elastic-docs-skills/tree/main/skills/authoring/applies-to-tagging) skill in Claude Code to validate and generate `applies_to` tags. [**Learn more**](https://github.com/elastic/elastic-docs-skills/tree/main#elastic-docs-skills) +::: -* Which Elastic products and deployment models the content applies to. -* When a feature changes state relative to the base version. +## Quick reference -This is what the `applies_to` metadata is for. It can be used at the [page](#page-level), [section](#section-level), or [inline](#inline-level) level to specify applicability with precision. +When documenting a new feature or behavior: -:::{note} -For detailed guidance, refer to [Write cumulative documentation](https://www.elastic.co/docs/contribute-docs/how-to/cumulative-docs). -::: +1. **Where should I add `applies_to` metadata?** Find where your changes sit on the page and match to a type below. +2. **What keys and values do I use?** Refer to the [key-value reference](#key-value-reference) for the full list of valid keys, lifecycles, and version formats. + +### Where should I put the `applies_to` metadata? + +| When | Use | +|------|-----| +| You're creating a new page | [Frontmatter](#page-level) | +| You're adding a new section to an existing page | [Section-level annotation](#section-level) | +| You're adding a single new item to a list or definition term | [Inline annotation](#inline-level) | +| You're marking a single item as a technical preview | [Preview shorthand](#inline-level) | +| You need to show entirely different content for each variant, not just tag the same content | [Versioned tabs](applies-switch.md) | +| You're adding a version-specific note, tip, or warning | [Admonition annotation](admonitions.md) | +| You're adding a version-specific dropdown | [Dropdown annotation](dropdowns.md) | ## Syntax reference From 242c9ca32c572d3a645a4e4d7e24f373fc7de55c Mon Sep 17 00:00:00 2001 From: Liam Thompson Date: Fri, 5 Jun 2026 13:53:06 +0200 Subject: [PATCH 2/2] Fix lead-in sentence grammar in quick reference Co-Authored-By: Claude Opus 4.6 --- 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 9c33efcee..1c5895607 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -8,7 +8,7 @@ You can use the [applies-to-tagging](https://github.com/elastic/elastic-docs-ski ## Quick reference -When documenting a new feature or behavior: +When documenting a new feature or behavior, answer these two questions: 1. **Where should I add `applies_to` metadata?** Find where your changes sit on the page and match to a type below. 2. **What keys and values do I use?** Refer to the [key-value reference](#key-value-reference) for the full list of valid keys, lifecycles, and version formats.