Skip to content

Applies_to - Mention new supported components in more cumulative docs docs #2104

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 23, 2025
Merged

Applies_to - Mention new supported components in more cumulative docs docs #2104

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1a823aa
Mention new supported components in more relevant docs
florent-leborgne Oct 23, 2025
d211998
lolz
florent-leborgne Oct 23, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/contribute/cumulative-docs/_snippets/applies-switch-and-tabs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
:::
19 changes: 5 additions & 14 deletions docs/contribute/cumulative-docs/badge-placement.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -177,26 +177,17 @@ If needed, break the contents of the cell into multiple lines using `<br>` 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
% <image>
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
% <image>
:::{include} /syntax/_snippets/applies-to-dropdowns.md
:::

### Code blocks

Expand Down
12 changes: 12 additions & 0 deletions docs/contribute/cumulative-docs/example-scenarios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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]
Copy link
Contributor

@colleenmcginnis colleenmcginnis Oct 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we just update all these examples to use applies-switch instead of just adding a note? I'd be happy to help with that if you agree!!

Copy link
Contributor Author

@florent-leborgne florent-leborgne Oct 23, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Didn't want to completely force applies-switch over tabs for now because of ranges, etc. so I went with a tip snippet.

I went lazy mode for now until we have ranges and can use it in 100% of versioning cases, to avoid forcing one or the other onto people

Copy link
Contributor

@colleenmcginnis colleenmcginnis Oct 23, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooooooook.


:::{include} _snippets/applies-switch-and-tabs.md
:::

**When to use tabs**: If using a [code callout](#code-block-callout) isn't appropriate.

**Best practices**:
Expand Down Expand Up @@ -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**:
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
63 changes: 63 additions & 0 deletions docs/syntax/_snippets/applies-to-admonitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
:::
```

::::

:::::
19 changes: 19 additions & 0 deletions docs/syntax/_snippets/applies-to-dropdowns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
65 changes: 2 additions & 63 deletions docs/syntax/admonitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
:::
10 changes: 10 additions & 0 deletions docs/syntax/applies.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,6 +94,16 @@ Property {preview}`<version>`

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.
Expand Down
23 changes: 1 addition & 22 deletions docs/syntax/dropdowns.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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-admonitions.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.
Expand Down
Loading