Restructure doc and add inline examples

Author: theletterf

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,6 +10,9 @@
   * `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.
+
+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:
+
 * `product`: Applies to a specific product that uses a unique versioning scheme (e.g. 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).
@@ -30,7 +33,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.
+
+:::{important}
+A key without any value doesn't show any badge in the output.
 :::

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,7 +38,7 @@ 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.

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

@@ -0,0 +1,98 @@
+::::::{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
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+- {applies_to}`edot_python: preview 1.7.0`
+- {applies_to}`apm_agent_java: beta 1.0.0`
+- {applies_to}`elasticsearch: ga 9.1.0`
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+- {applies_to}`edot_python: preview 1.7.0`
+- {applies_to}`apm_agent_java: beta 1.0.0`
+- {applies_to}`elasticsearch: ga 9.1.0`
+```
+::::
+
+:::::
+
+::::::
+
+::::::{dropdown} Multiple products and states in a single inline statement
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+- {applies_to}`{ serverless: "ga" , stack: "ga 9.1.0" }`
+- {applies_to}`{ edot_python: "preview 1.7.0" , apm_agent_java: "beta 1.0.0" }`
+- {applies_to}`{ stack: "ga 9.0" , deployment: { eck: "ga 9.0" } }`
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+- {applies_to}`{ serverless: "ga" , stack: "ga 9.1.0" }`
+- {applies_to}`{ edot_python: "preview 1.7.0" , apm_agent_java: "beta 1.0.0" }`
+- {applies_to}`{ stack: "ga 9.0" , deployment: { eck: "ga 9.0" } }`
+```
+::::
+
+:::::
+
+::::::
+
+::::::{dropdown} Complex scenarios with different product types
+
+:::::{tab-set}
+
+::::{tab-item} Output
+
+- {applies_to}`{ stack: "preview 9.1", product: { edot_python: "preview 1.4.0" } }`
+
+Notice that, when mixing different statement types, the applies_to inline syntax requires JSON-like nesting for product-specific applicability.
+
+::::
+
+::::{tab-item} Markdown
+```markdown
+- {applies_to}`{ stack: "preview 9.1", product: { edot_python: "preview 1.4.0" } }`
+```
+
+Notice that, when mixing different statement types, the applies_to inline syntax requires JSON-like nesting for product-specific applicability.
+
+::::
+
+:::::
+
+::::::

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}
+deployment:
+ess: ga
+serverless: ga
+```
+
+[...]
+
+#### Orchestrator level security [orchestrator-level]
+```{applies_to}
+deployment:
+ece: ga
+```
+
+[...]
+````
+:::::