You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Avoid using version numbers in prose adjacent to `applies_to` badge to prevent
21
19
confusion when the badge is rended with `Planned` ahead of a release.
@@ -27,47 +25,111 @@ Depending on what you're trying to communicate, you can use the following patter
27
25
* Do not assume a default deployment type, stack flavor, product version, or project type.
28
26
Treat all flavors and deployment types equally. Don't treat one as the "base" and the other as the "exception".
29
27
28
+
## Order of items
29
+
30
+
**Versions.** Always put the newest version first when listing multiple versions. As a result, the lifecycles should be in order of product development progression, too.
* List keys in the same order for consistency. This order reflects organizational priorities.
33
-
* Serverless
34
-
* Stack
35
-
* Elastic Cloud Hosted
36
-
* Elastic Cloud on Kubernetes
37
-
* Elastic Cloud Enterprise
38
-
* Self-managed
34
+
**Keys.** Always list [keys](/contribute/cumulative-docs/reference.md#key) in the same order for consistency. The order of keys should reflect organizational priorities. For example, use the following order:
***Headings**: Use section annotations immediately after the heading.
44
-
Do _not_ use inline annotations with headings, which will cause rendering issues in "On this page".
42
+
### Headings
43
+
44
+
Use [section annotations](/syntax/applies.md#section-annotations) immediately after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same and higher level.
45
+
46
+
For example, in the [Semantic text field type](https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/semantic-text#custom-by-pipelines) page, all the content in this section is only applicable to Elastic Stack versions 9.0.0 and later.
47
+
48
+
::::{image} ./images/heading-correct.png
49
+
:screenshot:
50
+
:alt: Correct use of applies_to with headings
51
+
::::
52
+
53
+
:::{warning}
54
+
Do **not** use [inline annotations](/syntax/applies.md#inline-annotations) with headings, which will cause rendering issues in _On this page_.
55
+
56
+
::::{image} ./images/heading-incorrect.png
57
+
:screenshot:
58
+
:alt: Rendering error when using inline applies_to with headings
***Definition lists**: If the `applies_to` badge is relevant to the entire contents of the list item,
48
-
put it at the end of the term (on the same line).
63
+
### Definition lists
64
+
65
+
The recommended placement of `applies_to` badges in definition lists varies based what part(s) of the list item relate to the badge.
66
+
67
+
**If the badge is relevant to the entire contents of a list item, put it at the end of the term.** This means using an inline annotation at the end of the same line as the term. For example, on the Kibana [Advanced settings](https://www.elastic.co/docs/reference/kibana/advanced-settings#kibana-banners-settings) page, the entire `banners:linkColor` option is only available in Elastic Stack 9.1.0 and later.
:alt: Incorrectly using inline applies_to with a definition list item
80
+
::::
81
+
:::
82
+
83
+
**If the badge is only relevant to a portion of the definition, follow the appropriate placement guidelines for the elements used in the definition.** This might include labeling just one of multiple paragraphs or one item in an ordered or unordered list. For example, on the ... page, ...
:alt: Correctly using inline applies_to in a portion of a definition list item
88
+
::::
49
89
50
90
% Reference: TBD
51
-
***Ordered and unordered lists**: Reorganize content as needed so the `applies_to` badge is relevant
52
-
to the entire contents of the list item. The recommended placement of the badge varies:
53
-
* If the purpose of the list is to illustrate the difference between several applications (deployment types,
54
-
products, lifecycles, versions, etc.) put an `applies_to` badge at the start of each item.
55
-
* If the list just happens to have one or more items that are only relevant to specific application
56
-
(deployment type, product, lifecycle, version, etc.) put the `applies_to` badge at the end of the list item.
91
+
### Ordered and unordered lists
92
+
93
+
Reorganize content as needed so the `applies_to` badge is relevant to the entire contents of the list item.
94
+
The recommended placement of the badge varies based on the purpose of the list.
95
+
96
+
**If the purpose of the list is to illustrate the difference between situations, put a badge at the start of each item.**
97
+
This could mean distinguishing between deployment types, products, lifecycles, or versions.
98
+
For example, the [Alerting and action settings in Kibana](https://www.elastic.co/docs/reference/kibana/configuration-reference/alerting-settings) page lists how the default value for the `xpack.actions.preconfigured.<connector-id>.config.defaultModel` setting varies in Serverless/Stack and across versions.
99
+
100
+
::::{image} ./images/list-correct.png
101
+
:screenshot:
102
+
:alt:
103
+
::::
104
+
105
+
**If the list just happens to have one or more items that are only relevant to a specific situation, put the badge at the end of the list item.**
0 commit comments