Skip to content

Commit 1a823aa

Browse files
florent-leborgneflorent-leborgne
committed
Mention new supported components in more relevant docs
1 parent ae22882 commit 1a823aa

File tree

8 files changed

+118
-99
lines changed

8 files changed

+118
-99
lines changed

‎docs/contribute/cumulative-docs/_snippets/applies-switch-and-tabs.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
:::{tip} - Use applies-switch instead of traditional tabs
2+
3+
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).
4+
5+
**Applies-switch** natively support using `applies_to` metadata keys as tab titles and offer a more consistent experience with recognizable badges.
6+
:::

‎docs/contribute/cumulative-docs/badge-placement.md‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -177,26 +177,17 @@ If needed, break the contents of the cell into multiple lines using `<br>` to is
177177

178178
### Tabs
179179

180-
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.
181-
182-
% TO DO: Add example
183-
% <image>
180+
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.
184181

185182
### Admonitions
186183

187-
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.
188-
189-
::::{image} ./images/admonition-correct.png
190-
:screenshot:
191-
:alt:
192-
::::
184+
:::{include} /syntax/_snippets/applies-to-admonitions.md
185+
:::
193186

194187
### Dropdowns
195188

196-
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.
197-
198-
% TO DO: Add example
199-
% <image>
189+
:::{include} /syntax/_snippets/applies-to-dropdowns.md
190+
:::
200191

201192
### Code blocks
202193

‎docs/contribute/cumulative-docs/example-scenarios.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -400,6 +400,9 @@ Using a code callout is the lightest-touch solution, but might not be sufficient
400400

401401
### Solution B: Use tabs [code-block-tabs]
402402

403+
:::{include} _snippets/applies-switch-and-tabs.md
404+
:::
405+
403406
**When to use tabs**: If using a [code callout](#code-block-callout) isn't appropriate.
404407

405408
**Best practices**:
@@ -443,6 +446,9 @@ but might not be sufficient in all cases.
443446

444447
### Solution B: Use tabs [workflow-tabs]
445448

449+
:::{include} _snippets/applies-switch-and-tabs.md
450+
:::
451+
446452
Tabs are minimally disruptive in many situations.
447453

448454
**When to use tabs**:
@@ -497,6 +503,9 @@ Sometimes the UI differs between versions, deployment types or other conditions.
497503

498504
### Solution A: Use tabs [screenshot-tabs]
499505

506+
:::{include} _snippets/applies-switch-and-tabs.md
507+
:::
508+
500509
**When to use tabs**:
501510
* When the screenshot shows significantly different interfaces or workflows for each product, deployment type, or version.
502511
* 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
533542

534543
### Solution A: Use tabs [multiple-block-tabs]
535544

545+
:::{include} _snippets/applies-switch-and-tabs.md
546+
:::
547+
536548
**When to use tabs**:
537549
* When the content is structurally similar but differs in detail — for example, slightly different instructions, outputs, or paths.
538550
* When you want to avoid repeating most of the surrounding content and isolate just the difference.

‎docs/syntax/_snippets/applies-to-admonitions.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
Admonitions support the `applies_to` property to indicate which products or versions the information applies to.
2+
3+
:::::{tab-set}
4+
5+
::::{tab-item} Output
6+
7+
:::{note}
8+
:applies_to: stack: ga 9.1.0
9+
10+
This note applies to the Elastic Stack GA version 9.1.0.
11+
:::
12+
13+
:::{warning}
14+
:applies_to: serverless: ga
15+
16+
This warning applies to serverless GA.
17+
:::
18+
19+
:::{tip}
20+
:applies_to: { ess:, ece: }
21+
22+
This tip applies to ECH and ECE.
23+
:::
24+
25+
:::{important}
26+
:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"}
27+
28+
This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA.
29+
:::
30+
31+
::::
32+
33+
::::{tab-item} Markdown
34+
35+
```markdown
36+
:::{note}
37+
:applies_to: stack: ga 9.1.0
38+
39+
This note applies to the Elastic Stack GA version 9.1.0.
40+
:::
41+
42+
:::{warning}
43+
:applies_to: serverless: ga
44+
45+
This warning applies to serverless GA.
46+
:::
47+
48+
:::{tip}
49+
:applies_to: { ess:, ece: }
50+
51+
This tip applies to ECH and ECE.
52+
:::
53+
54+
:::{important}
55+
:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"}
56+
57+
This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA.
58+
:::
59+
```
60+
61+
::::
62+
63+
:::::

‎docs/syntax/_snippets/applies-to-dropdowns.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
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.
2+
3+
**Source**
4+
5+
```markdown
6+
:::{dropdown} Dropdown Title
7+
:applies_to: stack: ga 9.0
8+
Dropdown content for Stack GA 9.0
9+
:::
10+
```
11+
12+
**Rendering**
13+
14+
:::{dropdown} Dropdown Title
15+
:applies_to: stack: ga 9.0
16+
Dropdown content for Stack GA 9.0
17+
:::
18+
19+
You can also specify multiple definitions in the same `:applies_to:` parameter. For example, `:applies_to: { ece:, ess: }` renders both ECE and ECH badges.

‎docs/syntax/admonitions.md‎

Lines changed: 2 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -152,66 +152,5 @@ It can *span* multiple lines and supports inline formatting.
152152

153153
## Applies to information
154154

155-
Admonitions support the `applies_to` property to indicate which products or versions the information applies to.
156-
157-
:::::{tab-set}
158-
159-
::::{tab-item} Output
160-
161-
:::{note}
162-
:applies_to: stack: ga 9.1.0
163-
164-
This note applies to the Elastic Stack GA version 9.1.0.
165-
:::
166-
167-
:::{warning}
168-
:applies_to: serverless: ga
169-
170-
This warning applies to serverless GA.
171-
:::
172-
173-
:::{tip}
174-
:applies_to: { ess:, ece: }
175-
176-
This tip applies to ECH and ECE.
177-
:::
178-
179-
:::{important}
180-
:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"}
181-
182-
This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA.
183-
:::
184-
185-
::::
186-
187-
::::{tab-item} Markdown
188-
189-
```markdown
190-
:::{note}
191-
:applies_to: stack: ga 9.1.0
192-
193-
This note applies to the Elastic Stack GA version 9.1.0.
194-
:::
195-
196-
:::{warning}
197-
:applies_to: serverless: ga
198-
199-
This warning applies to serverless GA.
200-
:::
201-
202-
:::{tip}
203-
:applies_to: { ess:, ece: }
204-
205-
This tip applies to ECH and ECE.
206-
:::
207-
208-
:::{important}
209-
:applies_to: {"stack": "ga 9.2, preview 9.1", "serverless": "ga"}
210-
211-
This important note applies to Elastic Stack GA version 9.2 and Elastic Stack Preview version 9.1. It also applies to serverless GA.
212-
:::
213-
```
214-
215-
::::
216-
217-
:::::
155+
:::{include} _snippets/applies-to-admonitions.md
156+
:::

‎docs/syntax/applies.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,16 @@ Property {preview}`<version>`
9494

9595
For more examples, refer to [Inline annotation examples](#inline-annotation-examples).
9696

97+
### On specific components
98+
99+
Several components have built-in support for `applies_to` and allow to surface version information in an optimized way:
100+
101+
- [applies-switch](applies-switch.md), a component similar to tabs but with specific support to show version badges as tab titles
102+
- [admonitions](admonitions.md)
103+
- [dropdowns](dropdowns.md)
104+
105+
Refer to these component pages to learn about the required `applies_to` syntax.
106+
97107
## Key-value reference
98108

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

‎docs/syntax/dropdowns.md‎

Lines changed: 1 addition & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -53,30 +53,9 @@ Dropdown content
5353

5454
## With applies_to badge
5555

56-
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.
57-
58-
:::::{tab-set}
59-
60-
::::{tab-item} Output
61-
62-
:::{dropdown} Dropdown Title
63-
:applies_to: stack: ga 9.0
64-
Dropdown content for Stack GA 9.0
56+
:::{include} _snippets/applies-to-admonitions.md
6557
:::
6658

67-
::::
68-
69-
::::{tab-item} Markdown
70-
```markdown
71-
:::{dropdown} Dropdown Title
72-
:applies_to: stack: ga 9.0
73-
Dropdown content for Stack GA 9.0
74-
:::
75-
```
76-
::::
77-
78-
:::::
79-
8059
## Multiple applies_to definitions
8160

8261
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.

0 commit comments

Comments
 (0)