Restructure doc and add inline examples (#1793)

* Restructure doc and add inline examples

* Update docs/syntax/applies.md

Co-authored-by: Colleen McGinnis <[email protected]>

* Update docs/syntax/_snippets/inline-level-applies-examples.md

Co-authored-by: Colleen McGinnis <[email protected]>

* Peer edits

* Move examples

* Move section

* Clarify note

* Update docs/syntax/_snippets/inline-level-applies-examples.md

Co-authored-by: florent-leborgne <[email protected]>

* Update docs/syntax/applies.md

Co-authored-by: Colleen McGinnis <[email protected]>

* Update docs/_snippets/applies_to-key.md

Co-authored-by: Colleen McGinnis <[email protected]>

* Update docs/syntax/_snippets/section-level-applies-examples.md

Co-authored-by: Colleen McGinnis <[email protected]>

* Update docs/syntax/_snippets/section-level-applies-examples.md

Co-authored-by: Colleen McGinnis <[email protected]>

* Update docs/syntax/quick-ref.md

Co-authored-by: Colleen McGinnis <[email protected]>

---------

Co-authored-by: Colleen McGinnis <[email protected]>
Co-authored-by: florent-leborgne <[email protected]>

Author: 3 people

docs/_snippets/applies_to-key.md

@@ -1,4 +1,4 @@
-`applies_to` accepts the following keys in this structure:
+`applies_to` accepts the following keys in this structure.
 
 * `serverless`: Applies to [Elastic Cloud Serverless](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/serverless).
   * `security`: Applies to Serverless [security projects](https://www.elastic.co/docs/solutions/security/get-started/create-security-project).
@@ -10,7 +10,7 @@
   * `eck`: Applies to [Elastic Cloud on Kubernetes](https://www.elastic.co/docs/deploy-manage/deploy/cloud-on-k8s) deployments.
   * `self`: Applies to [self-managed](https://www.elastic.co/docs/deploy-manage/deploy/self-managed) deployments.
   * `ess`: Applies to [Elastic Cloud Hosted](https://www.elastic.co/docs/deploy-manage/deploy/elastic-cloud/cloud-hosted) deployments.
-* `product`: Applies to a specific product that uses a unique versioning scheme (e.g. not `stack`, `ece`, `eck`).
+* `product`: Applies to a specific product that uses a unique versioning scheme (for example, not `stack`, `ece`, `eck`).
   * `apm_agent_dotnet`: Applies to the [Elastic APM .NET agent](https://www.elastic.co/docs/reference/apm/agents/dotnet).
   * `apm_agent_go`: Applies to the [Elastic APM Go agent](https://www.elastic.co/docs/reference/apm/agents/go).
   * `apm_agent_java`: Applies to the [Elastic APM Java agent](https://www.elastic.co/docs/reference/apm/agents/java).
@@ -30,7 +30,7 @@
   * `edot_node`: Applies to the [Elastic Distribution of OpenTelemetry Node.js](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/nodejs/) (EDOT Node.js).
   * `edot_php`: Applies to the [Elastic Distribution of OpenTelemetry PHP](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/php/) (EDOT PHP).
   * `edot_python`: Applies to the [Elastic Distribution of OpenTelemetry Python](https://www.elastic.co/docs/reference/opentelemetry/edot-sdks/python/) (EDOT Python).
-  
+
 :::{note}
-The `products` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters.
+The `product` key and its subkeys are used to indicate feature availability and applicability. The similarly named [`products` frontmatter field](/syntax/frontmatter.md#products) is used to drive elastic.co search filters.
 :::

docs/_snippets/applies_to-version.md

@@ -3,7 +3,8 @@
 * `Major.Minor`
 * `Major.Minor.Patch`
 
+Regardless of the version format used in the source file, the version number is always rendered in the `Major.Minor.Patch` format.
+
 :::{note}
-Regardless of the version format used in the source file,
-the version number will always be rendered in the `Major.Minor.Patch` format.
-:::
+**Automatic Version Sorting**: When you specify multiple versions for the same product, the build system automatically sorts them in descending order (highest version first) regardless of the order you write them in the source file. For example, `stack: ga 8.18.6, ga 9.1.2, ga 8.19.2, ga 9.0.6` will be displayed as `stack: ga 9.1.2, ga 9.0.6, ga 8.19.2, ga 8.18.6`. Items without versions (like `ga` without a version or `all`) are sorted last.
+:::

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

@@ -38,15 +38,15 @@ There are more specific guidelines on badge placement to follow when using speci
 
 ### Page frontmatter
 
-Use [`applies_to` in a page's frontmatter](/syntax/applies.md#page-annotations) to provide signals that a page applies to the reader.
+Use [`applies_to` in a page's frontmatter](/syntax/applies.md#syntax) to provide signals that a page applies to the reader.
 
 ::::{warning}
-Do **not** use [section-level](/syntax/applies.md#section-annotations) or [inline annotations](/syntax/applies.md#inline-annotations) with the page title.
+Do **not** use [section-level](/syntax/applies.md#section-level) or [inline annotations](/syntax/applies.md#inline-level) with the page title.
 ::::
 
 ### Headings [headings]
 
-Use [section annotations](/syntax/applies.md#section-annotations) on the next line after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same or higher level is version or product-specific.
+Use [section annotations](/syntax/applies.md#section-level) on the next line after a heading when the entire content between that heading and the next [heading](/syntax/headings.md) of the same or higher level is version or product-specific.
 
 For example, on the [Observability AI Assistant](https://www.elastic.co/docs/solutions/observability/observability-ai-assistant#choose-the-knowledge-base-language-model) page, all the content in this section is only applicable to Elastic Stack versions 9.1.0 and later.
 
@@ -58,7 +58,7 @@ For example, on the [Observability AI Assistant](https://www.elastic.co/docs/sol
 % FOR THE REVIEWER: IS THIS TRUE?
 % What do you think of allowing inline applies_to in headings as long as there is only one badge?
 :::{warning}
-Do **not** use [inline annotations](/syntax/applies.md#inline-annotations) with headings.
+Do **not** use [inline annotations](/syntax/applies.md#inline-level) with headings.
 
 ::::{image} ./images/heading-incorrect.png
 :screenshot:

docs/syntax/_snippets/inline-level-applies-examples.md

@@ -0,0 +1,73 @@
+::::::{dropdown} Basic example
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+**Spaces** let you organize your content and users according to your needs.
+
+- Each space has its own saved objects.
+- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view.
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+**Spaces** let you organize your content and users according to your needs.
+
+- Each space has its own saved objects.
+- {applies_to}`serverless: unavailable` Each space has its own navigation, called solution view.
+```
+::::
+
+:::::
+
+::::::
+
+::::::{dropdown} Product-specific applicability with version information
+
+This example shows how to use directly a key from the second level of the `applies_to` data structure, like `edot_python:`.
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+- {applies_to}`edot_python: preview 1.7.0`
+- {applies_to}`apm_agent_java: beta 1.0.0`
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+- {applies_to}`edot_python: preview 1.7.0`
+- {applies_to}`apm_agent_java: beta 1.0.0`
+```
+::::
+
+:::::
+
+::::::
+
+::::::{dropdown} Multiple products and states in a single inline statement
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+- {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0`
+- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0`
+- {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0`
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+- {applies_to}`serverless: ga` {applies_to}`stack: ga 9.1.0`
+- {applies_to}`edot_python: preview 1.7.0, ga 1.8.0` {applies_to}`apm_agent_java: beta 1.0.0, ga 1.2.0`
+- {applies_to}`stack: ga 9.0` {applies_to}`eck: ga 3.0`
+```
+::::
+
+:::::
+::::::
+

docs/syntax/_snippets/line-level-applies-example.md

@@ -1,16 +1,16 @@
-There are 3 typical scenarios to start from:
+:::::{dropdown} Document is primarily about using or interacting with Elastic Stack components or the Serverless UI
 
-* The documentation set or page is primarily about using or interacting with Elastic Stack components or the Serverless UI:
+   ```yml
+   --- 
+   applies_to:
+     stack: ga
+     serverless: ga
+   ---
+   ```
 
-    ```yml
-    --- 
-    applies_to:
-      stack: ga
-      serverless: ga
-    ---
-    ```
+:::::
 
-* The documentation set or page is primarily about orchestrating, deploying or configuring an installation (only include relevant keys):
+:::::{dropdown} Document is primarily about orchestrating, deploying or configuring an installation
 
   ```yml
   --- 
@@ -24,7 +24,9 @@ There are 3 typical scenarios to start from:
 
   ```
 
-* The documentation set or page is primarily about a product following its own versioning schema:
+:::::
+
+:::::{dropdown} Document is primarily about a product following its own versioning schema
 
   ```yml
   --- 
@@ -33,21 +35,4 @@ There are 3 typical scenarios to start from:
   ---
   ```
 
-It can happen that it’s relevant to identify several or all of these dimensions for a page. Use your own judgement and check existing pages in similar contexts.
-
-```yml
---- 
-applies_to:
-  stack: ga
-  serverless: ga
-  deployment: 
-    ess: ga
-    ece: ga
-    eck: ga
----
-```
-% I don't know what this example is supposed to show
-
-
-
-
+:::::

docs/syntax/_snippets/page-level-applies-examples.md

@@ -1,40 +1,41 @@
-* The whole page is generally applicable to {{stack}} 9.0 and to {{serverless-short}}, but one specific section isn’t applicable to {{serverless-short}} (and there is no alternative for it):
-
-    ````md
-    --- 
-    applies_to:
-      stack: ga
-      serverless: ga
-    ---
-
-    # Spaces
-
-    [...]
-
-    ## Configure a space-level landing page [space-landing-page]
-    ```{applies_to}
-    serverless: unavailable
-    ```
-    ````
-    % I think we wanted to not specify stack here
-
-* The whole page is generally applicable to all deployment types, but one specific paragraph only applies to {{ech}} and {{serverless-short}}, and another paragraph only applies to {{ece}}:
-
-  ````md
-  ## Cloud organization level security [cloud-organization-level]
-  ```{applies_to}
-  deployment:
-    ess: ga
-  serverless: ga
-  ```
-
-  [...]
-
-  ## Orchestrator level security [orchestrator-level]
-  ```{applies_to}
-  deployment:
-    ece: ga
-  ```
-
-  [...]
-  ````
+:::::{dropdown} Applicable to Stack and Serverless, minus a section
+
+````markdown
+--- 
+applies_to:
+stack: ga
+serverless: ga
+---
+
+# Spaces
+
+[...]
+
+#### Configure a space-level landing page [space-landing-page]
+```{applies_to}
+serverless: unavailable
+```
+````
+:::::
+
+:::::{dropdown} Applicable to all deployment types, but some paragraphs are specific to other deployment types
+
+````markdown
+#### Cloud organization level security [cloud-organization-level]
+```{applies_to}
+serverless: ga
+deployment:
+  ess: ga
+```
+
+[...]
+
+#### Orchestrator level security [orchestrator-level]
+```{applies_to}
+deployment:
+  ece: ga
+```
+
+[...]
+````
+:::::