diff --git a/docs/contribute/cumulative-docs/_snippets/applies-switch-and-tabs.md b/docs/contribute/cumulative-docs/_snippets/applies-switch-and-tabs.md new file mode 100644 index 000000000..6573169a6 --- /dev/null +++ b/docs/contribute/cumulative-docs/_snippets/applies-switch-and-tabs.md @@ -0,0 +1,6 @@ +:::{tip} - Use applies-switch instead of traditional tabs + +When you'd like to build a tabbed experience for content that varies specifically between two or more versions, or between two or more deployment types, prefer using [applies-switch](/syntax/applies-switch.md) over regular [tabs](/syntax/tabs.md). + +**Applies-switch** natively support using `applies_to` metadata keys as tab titles and offer a more consistent experience with recognizable badges. +::: \ No newline at end of file diff --git a/docs/contribute/cumulative-docs/badge-placement.md b/docs/contribute/cumulative-docs/badge-placement.md index f9d127e3a..c333572fd 100644 --- a/docs/contribute/cumulative-docs/badge-placement.md +++ b/docs/contribute/cumulative-docs/badge-placement.md @@ -177,26 +177,17 @@ If needed, break the contents of the cell into multiple lines using `
` to is ### Tabs -In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), tabs will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire tab item, add the badge to the beginning of the content. - -% TO DO: Add example -% +When you need to show versions as tab titles, consider using [applies-switch](/syntax/applies-switch.md) instead. The applies-switch component has built-in support for using applies-to metadata as tab titles and render these as badges. ### Admonitions -In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), admonitions will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire admonition, add the badge to the beginning of the content. - -::::{image} ./images/admonition-correct.png -:screenshot: -:alt: -:::: +:::{include} /syntax/_snippets/applies-to-admonitions.md +::: ### Dropdowns -In the future ([elastic/docs-builder#1436](https://github.com/elastic/docs-builder/issues/1436)), dropdowns will be able to accept `applies_to` information. Until then, if an `applies_to` badge is relevant to the entire dropdown, add the badge to the beginning of the content. - -% TO DO: Add example -% +:::{include} /syntax/_snippets/applies-to-dropdowns.md +::: ### Code blocks diff --git a/docs/contribute/cumulative-docs/example-scenarios.md b/docs/contribute/cumulative-docs/example-scenarios.md index 31ef9442a..ddaae4c4f 100644 --- a/docs/contribute/cumulative-docs/example-scenarios.md +++ b/docs/contribute/cumulative-docs/example-scenarios.md @@ -400,6 +400,9 @@ Using a code callout is the lightest-touch solution, but might not be sufficient ### Solution B: Use tabs [code-block-tabs] +:::{include} _snippets/applies-switch-and-tabs.md +::: + **When to use tabs**: If using a [code callout](#code-block-callout) isn't appropriate. **Best practices**: @@ -443,6 +446,9 @@ but might not be sufficient in all cases. ### Solution B: Use tabs [workflow-tabs] +:::{include} _snippets/applies-switch-and-tabs.md +::: + Tabs are minimally disruptive in many situations. **When to use tabs**: @@ -497,6 +503,9 @@ Sometimes the UI differs between versions, deployment types or other conditions. ### Solution A: Use tabs [screenshot-tabs] +:::{include} _snippets/applies-switch-and-tabs.md +::: + **When to use tabs**: * When the screenshot shows significantly different interfaces or workflows for each product, deployment type, or version. * When the screenshot represents a specific, interactive action, like clicking a button or navigating a UI that changes meaningfully between contexts. @@ -533,6 +542,9 @@ For example, versioning the screenshot on the [Dashboards](https://www.elastic.c ### Solution A: Use tabs [multiple-block-tabs] +:::{include} _snippets/applies-switch-and-tabs.md +::: + **When to use tabs**: * When the content is structurally similar but differs in detail — for example, slightly different instructions, outputs, or paths. * When you want to avoid repeating most of the surrounding content and isolate just the difference. diff --git a/docs/syntax/_snippets/applies-to-admonitions.md b/docs/syntax/_snippets/applies-to-admonitions.md new file mode 100644 index 000000000..d76c1c4e4 --- /dev/null +++ b/docs/syntax/_snippets/applies-to-admonitions.md @@ -0,0 +1,63 @@ +Admonitions support the `applies_to` property to indicate which products or versions the information applies to. + +:::::{tab-set} + +::::{tab-item} Output + +:::{note} +:applies_to: stack: ga 9.1.0 + +This note applies to the Elastic Stack GA version 9.1.0. +::: + +:::{warning} +:applies_to: serverless: ga + +This warning applies to serverless GA. +::: + +:::{tip} +:applies_to: { ess:, ece: } + +This tip applies to ECH and ECE. +::: + +:::{important} +:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"} + +This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA. +::: + +:::: + +::::{tab-item} Markdown + +```markdown +:::{note} +:applies_to: stack: ga 9.1.0 + +This note applies to the Elastic Stack GA version 9.1.0. +::: + +:::{warning} +:applies_to: serverless: ga + +This warning applies to serverless GA. +::: + +:::{tip} +:applies_to: { ess:, ece: } + +This tip applies to ECH and ECE. +::: + +:::{important} +:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"} + +This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA. +::: +``` + +:::: + +::::: \ No newline at end of file diff --git a/docs/syntax/_snippets/applies-to-dropdowns.md b/docs/syntax/_snippets/applies-to-dropdowns.md new file mode 100644 index 000000000..403389fc9 --- /dev/null +++ b/docs/syntax/_snippets/applies-to-dropdowns.md @@ -0,0 +1,19 @@ +You can add an applies_to badge to the dropdown title by specifying the `:applies_to:` option. This displays a badge indicating which deployment types, versions, or other applicability criteria the dropdown content applies to. + +**Source** + +```markdown +:::{dropdown} Dropdown Title +:applies_to: stack: ga 9.0 +Dropdown content for Stack GA 9.0 +::: +``` + +**Rendering** + +:::{dropdown} Dropdown Title +:applies_to: stack: ga 9.0 +Dropdown content for Stack GA 9.0 +::: + +You can also specify multiple definitions in the same `:applies_to:` parameter. For example, `:applies_to: { ece:, ess: }` renders both ECE and ECH badges. \ No newline at end of file diff --git a/docs/syntax/admonitions.md b/docs/syntax/admonitions.md index c4a7f466d..9f0096a5a 100644 --- a/docs/syntax/admonitions.md +++ b/docs/syntax/admonitions.md @@ -152,66 +152,5 @@ It can *span* multiple lines and supports inline formatting. ## Applies to information -Admonitions support the `applies_to` property to indicate which products or versions the information applies to. - -:::::{tab-set} - -::::{tab-item} Output - -:::{note} -:applies_to: stack: ga 9.1.0 - -This note applies to the Elastic Stack GA version 9.1.0. -::: - -:::{warning} -:applies_to: serverless: ga - -This warning applies to serverless GA. -::: - -:::{tip} -:applies_to: { ess:, ece: } - -This tip applies to ECH and ECE. -::: - -:::{important} -:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"} - -This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA. -::: - -:::: - -::::{tab-item} Markdown - -```markdown -:::{note} -:applies_to: stack: ga 9.1.0 - -This note applies to the Elastic Stack GA version 9.1.0. -::: - -:::{warning} -:applies_to: serverless: ga - -This warning applies to serverless GA. -::: - -:::{tip} -:applies_to: { ess:, ece: } - -This tip applies to ECH and ECE. -::: - -:::{important} -:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"} - -This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA. -::: -``` - -:::: - -::::: +:::{include} _snippets/applies-to-admonitions.md +::: \ No newline at end of file diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index 365c22f47..d36dddc2f 100644 --- a/docs/syntax/applies.md +++ b/docs/syntax/applies.md @@ -94,6 +94,16 @@ Property {preview}`` For more examples, refer to [Inline annotation examples](#inline-annotation-examples). +### On specific components + +Several components have built-in support for `applies_to` and allow to surface version information in an optimized way: + +- [applies-switch](applies-switch.md), a component similar to tabs but with specific support to show version badges as tab titles +- [admonitions](admonitions.md) +- [dropdowns](dropdowns.md) + +Refer to these component pages to learn about the required `applies_to` syntax. + ## Key-value reference Use the following key-value reference to find the appropriate key and value for your applicability statements. diff --git a/docs/syntax/dropdowns.md b/docs/syntax/dropdowns.md index a8b4f9a60..f4f4fd74e 100644 --- a/docs/syntax/dropdowns.md +++ b/docs/syntax/dropdowns.md @@ -53,30 +53,9 @@ Dropdown content ## With applies_to badge -You can add an applies_to badge to the dropdown title by specifying the `:applies_to:` option. This displays a badge indicating which deployment types, versions, or other applicability criteria the dropdown content applies to. - -:::::{tab-set} - -::::{tab-item} Output - -:::{dropdown} Dropdown Title -:applies_to: stack: ga 9.0 -Dropdown content for Stack GA 9.0 +:::{include} _snippets/applies-to-dropdowns.md ::: -:::: - -::::{tab-item} Markdown -```markdown -:::{dropdown} Dropdown Title -:applies_to: stack: ga 9.0 -Dropdown content for Stack GA 9.0 -::: -``` -:::: - -::::: - ## Multiple applies_to definitions You can specify multiple `applies_to` definitions using YAML object notation with curly braces `{}`. This is useful when content applies to multiple deployment types or versions simultaneously.