Update applies_to Stack/Serverless/Deploy/Product render order (#1727)

* update applies_to render order

Signed-off-by: bmorelli25 <[email protected]>

* more complex test

Signed-off-by: bmorelli25 <[email protected]>

* Add brief docs

Signed-off-by: bmorelli25 <[email protected]>

* clean

* ECH,ECK,ECE,SELF

Signed-off-by: bmorelli25 <[email protected]>

* test deployment type order

Signed-off-by: bmorelli25 <[email protected]>

* add docs

Signed-off-by: bmorelli25 <[email protected]>

---------

Signed-off-by: bmorelli25 <[email protected]>

Author: bmorelli25

docs/contribute/cumulative-docs/guidelines.md

@@ -115,22 +115,37 @@ You generally do not need to tag:
 
 ### Versions
 
-Always put the newest version first when listing multiple versions. As a result, the lifecycles should be in reverse order of product development progression, too.
+When listing multiple versions, author the newest version first whenever possible. This keeps files consistent and easier to maintain.
+Regardless of the source file, the build system automatically builds badge lifecycles in reverse chronological order.
+This means that badges will always appear to users from newest to oldest, which is the reverse of the product development timeline.
 
-% TO DO: Add example / image
-% <image>
+For example:
+
+{applies_to}`stack: preview 9.0.5, beta 9.1, ga 9.2`
 
-% Reference: https://elastic.github.io/docs-builder/versions/#defaults-and-hierarchy
-% Needs work...
 ### 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:
-* **Serverless/Elastic Stack**: Serverless, Stack
-* **Deployment types**: Elastic Cloud Serverless, Elastic Cloud Hosted, Elastic Cloud on Kubernetes, Elastic Cloud Enterprise, Self-managed
-* **Monitoring for Java applications**: Elastic Distribution of OpenTelemetry (EDOT) Java, APM Java agent
+The build system automatically orders multiple [keys](/contribute/cumulative-docs/reference.md#key) in a consistent pattern. This reduces authoring overhead and makes content easier for users to scan.
+
+:::{important}
+Key ordering only occurs if all keys are declared in the same directive. Keys declared seperately, for example: ``` {applies_to}`stack: ga` {applies_to}`serverless: preview` ```, will not be reordered by docs-builder.
+:::
+
+Keys are ordered as follows:
 
-% TO DO: Add example / image
-% <image>
+1. **Stack/Serverless**: Stack, Serverless
+2. **Deployment types**: ECH (Elastic Cloud Hosted), ECK (Elastic Cloud on Kubernetes), ECE (Elastic Cloud Enterprise), Self-Managed
+3. **ProductApplicability**: ECCTL, Curator, EDOT items (alphabetically), APM Agent items (alphabetically)
+
+For example:
+
+```{applies_to}
+deployment:
+  ece: ga
+  self: ga
+stack: ga
+serverless: ga
+```
 
 ## Product and deployment model applicability [products-and-deployment-models]
 

docs/syntax/applies.md

@@ -287,3 +287,15 @@ nec dignissim. Vestibulum ut felis nec massa auctor placerat. Maecenas vel dictu
 | `` {applies_to}`serverless: beta` ``            | {applies_to}`serverless: beta`            |
 | `` {applies_to}`serverless: deprecated` ``      | {applies_to}`serverless: deprecated`      |
 | `` {applies_to}`serverless: removed` ``         | {applies_to}`serverless: removed`         |
+
+### Badge rendering order
+
+`applies_to` badges are displayed in a consistent order regardless of how they appear in your source files. This ensures users always see badges in a predictable hierarchy:
+
+1. **Stack** - Elastic Stack
+2. **Serverless** - Elastic Cloud Serverless offerings
+3. **Deployment** - Deployment options (ECH, ECK, ECE, Self-Managed)
+4. **ProductApplicability** - Specialized tools and agents (ECCTL, Curator, EDOT, APM Agents)
+5. **Product (generic)** - Generic product applicability
+
+Within the ProductApplicability category, EDOT and APM Agent items are sorted alphabetically for easy scanning.

src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml

@@ -17,47 +17,6 @@
 		appliesTo.Stack
 	)
 }
-@if (appliesTo.Deployment is not null)
-{
-	if (appliesTo.Deployment.Ece is not null)
-	{
-		@RenderProduct("ECE",
-			"Elastic Cloud Enterprise",
-			VersioningSystemId.Ece,
-			appliesTo.Deployment.Ece
-		)
-	}
-
-	if (appliesTo.Deployment.Eck is not null)
-	{
-		@RenderProduct(
-			"ECK",
-			"Elastic Cloud on Kubernetes",
-			VersioningSystemId.Eck,
-			appliesTo.Deployment.Eck
-		)
-	}
-
-	if (appliesTo.Deployment.Ess is not null)
-	{
-		@RenderProduct(
-			"ECH",
-			"Elastic Cloud Hosted",
-			VersioningSystemId.Ess,
-			appliesTo.Deployment.Ess
-		)
-	}
-
-	if (appliesTo.Deployment.Self is not null)
-	{
-		@RenderProduct(
-			"Self-Managed",
-			"Self-managed Elastic deployments",
-			VersioningSystemId.Self,
-			appliesTo.Deployment.Self
-		)
-	}
-}
 @if (appliesTo.Serverless is not null)
 {
 	if (appliesTo.Serverless.AllProjects is not null)
@@ -102,9 +61,47 @@
 		}
 	}
 }
-@if (appliesTo.Product is not null)
+@if (appliesTo.Deployment is not null)
 {
-	@RenderProduct("", "", VersioningSystemId.All, appliesTo.Product)
+
+	if (appliesTo.Deployment.Ess is not null)
+	{
+		@RenderProduct(
+			"ECH",
+			"Elastic Cloud Hosted",
+			VersioningSystemId.Ess,
+			appliesTo.Deployment.Ess
+		)
+	}
+
+	if (appliesTo.Deployment.Eck is not null)
+	{
+		@RenderProduct(
+			"ECK",
+			"Elastic Cloud on Kubernetes",
+			VersioningSystemId.Eck,
+			appliesTo.Deployment.Eck
+		)
+	}
+
+	if (appliesTo.Deployment.Ece is not null)
+	{
+		@RenderProduct("ECE",
+			"Elastic Cloud Enterprise",
+			VersioningSystemId.Ece,
+			appliesTo.Deployment.Ece
+		)
+	}
+
+	if (appliesTo.Deployment.Self is not null)
+	{
+		@RenderProduct(
+			"Self-Managed",
+			"Self-managed Elastic deployments",
+			VersioningSystemId.Self,
+			appliesTo.Deployment.Self
+		)
+	}
 }
 @if (appliesTo.ProductApplicability is not null)
 {
@@ -119,101 +116,105 @@
 		@RenderProduct("Curator", "Curator", VersioningSystemId.Curator, pa.Curator)
 	}
 
-	if (pa.ApmAgentAndroid is not null)
+	if (pa.EdotAndroid is not null)
 	{
-		@RenderProduct("APM Agent Android", "Application Performance Monitoring Agent for Android", VersioningSystemId.ApmAgentAndroid, pa.ApmAgentAndroid)
+		@RenderProduct("EDOT Android", "Elastic Distribution of OpenTelemetry Android", VersioningSystemId.EdotAndroid, pa.EdotAndroid)
 	}
 
-	if (pa.ApmAgentDotnet is not null)
+	if (pa.EdotCfAws is not null)
 	{
-		@RenderProduct("APM Agent .NET", "Application Performance Monitoring Agent for .NET", VersioningSystemId.ApmAgentDotnet, pa.ApmAgentDotnet)
+		@RenderProduct("EDOT CF AWS", "Elastic Distribution of OpenTelemetry Cloud Forwarder for AWS", VersioningSystemId.EdotCfAws, pa.EdotCfAws)
 	}
 
-	if (pa.ApmAgentGo is not null)
+	if (pa.EdotCollector is not null)
 	{
-		@RenderProduct("APM Agent Go", "Application Performance Monitoring Agent for Go", VersioningSystemId.ApmAgentGo, pa.ApmAgentGo)
+		@RenderProduct("EDOT Collector", "Elastic Distribution of OpenTelemetry Collector", VersioningSystemId.EdotCollector, pa.EdotCollector)
 	}
 
-	if (pa.ApmAgentIos is not null)
+	if (pa.EdotDotnet is not null)
 	{
-		@RenderProduct("APM Agent iOS", "Application Performance Monitoring Agent for iOS", VersioningSystemId.ApmAgentIos, pa.ApmAgentIos)
+		@RenderProduct("EDOT .NET", "Elastic Distribution of OpenTelemetry .NET", VersioningSystemId.EdotDotnet, pa.EdotDotnet)
 	}
 
-	if (pa.ApmAgentJava is not null)
+	if (pa.EdotIos is not null)
 	{
-		@RenderProduct("APM Agent Java", "Application Performance Monitoring Agent for Java", VersioningSystemId.ApmAgentJava, pa.ApmAgentJava)
+		@RenderProduct("EDOT iOS", "Elastic Distribution of OpenTelemetry iOS", VersioningSystemId.EdotIos, pa.EdotIos)
 	}
 
-	if (pa.ApmAgentNode is not null)
+	if (pa.EdotJava is not null)
 	{
-		@RenderProduct("APM Agent Node.js", "Application Performance Monitoring Agent for Node.js", VersioningSystemId.ApmAgentNode, pa.ApmAgentNode)
+		@RenderProduct("EDOT Java", "Elastic Distribution of OpenTelemetry Java", VersioningSystemId.EdotJava, pa.EdotJava)
 	}
 
-	if (pa.ApmAgentPhp is not null)
+	if (pa.EdotNode is not null)
 	{
-		@RenderProduct("APM Agent PHP", "Application Performance Monitoring Agent for PHP", VersioningSystemId.ApmAgentPhp, pa.ApmAgentPhp)
+		@RenderProduct("EDOT Node.js", "Elastic Distribution of OpenTelemetry Node.js", VersioningSystemId.EdotNode, pa.EdotNode)
 	}
 
-	if (pa.ApmAgentPython is not null)
+	if (pa.EdotPhp is not null)
 	{
-		@RenderProduct("APM Agent Python", "Application Performance Monitoring Agent for Python", VersioningSystemId.ApmAgentPython, pa.ApmAgentPython)
+		@RenderProduct("EDOT PHP", "Elastic Distribution of OpenTelemetry PHP", VersioningSystemId.ApmAgentPhp, pa.EdotPhp)
 	}
 
-	if (pa.ApmAgentRuby is not null)
+	if (pa.EdotPython is not null)
 	{
-		@RenderProduct("APM Agent Ruby", "Application Performance Monitoring Agent for Ruby", VersioningSystemId.ApmAgentRuby, pa.ApmAgentRuby)
+		@RenderProduct("EDOT Python", "Elastic Distribution of OpenTelemetry Python", VersioningSystemId.EdotPython, pa.EdotPython)
 	}
 
-	if (pa.ApmAgentRum is not null)
+	if (pa.ApmAgentAndroid is not null)
 	{
-		@RenderProduct("APM Agent RUM", "Application Performance Monitoring Agent for Real User Monitoring", VersioningSystemId.ApmAgentRum, pa.ApmAgentRum)
+		@RenderProduct("APM Agent Android", "Application Performance Monitoring Agent for Android", VersioningSystemId.ApmAgentAndroid, pa.ApmAgentAndroid)
 	}
 
-	if (pa.EdotIos is not null)
+	if (pa.ApmAgentDotnet is not null)
 	{
-		@RenderProduct("EDOT iOS", "Elastic Distribution of OpenTelemetry iOS", VersioningSystemId.EdotIos, pa.EdotIos)
+		@RenderProduct("APM Agent .NET", "Application Performance Monitoring Agent for .NET", VersioningSystemId.ApmAgentDotnet, pa.ApmAgentDotnet)
 	}
 
-	if (pa.EdotAndroid is not null)
+	if (pa.ApmAgentGo is not null)
 	{
-		@RenderProduct("EDOT Android", "Elastic Distribution of OpenTelemetry Android", VersioningSystemId.EdotAndroid, pa.EdotAndroid)
+		@RenderProduct("APM Agent Go", "Application Performance Monitoring Agent for Go", VersioningSystemId.ApmAgentGo, pa.ApmAgentGo)
 	}
 
-	if (pa.EdotDotnet is not null)
+	if (pa.ApmAgentIos is not null)
 	{
-		@RenderProduct("EDOT .NET", "Elastic Distribution of OpenTelemetry .NET", VersioningSystemId.EdotDotnet, pa.EdotDotnet)
+		@RenderProduct("APM Agent iOS", "Application Performance Monitoring Agent for iOS", VersioningSystemId.ApmAgentIos, pa.ApmAgentIos)
 	}
 
-	if (pa.EdotJava is not null)
+	if (pa.ApmAgentJava is not null)
 	{
-		@RenderProduct("EDOT Java", "Elastic Distribution of OpenTelemetry Java", VersioningSystemId.EdotJava, pa.EdotJava)
+		@RenderProduct("APM Agent Java", "Application Performance Monitoring Agent for Java", VersioningSystemId.ApmAgentJava, pa.ApmAgentJava)
 	}
 
-	if (pa.EdotNode is not null)
+	if (pa.ApmAgentNode is not null)
 	{
-		@RenderProduct("EDOT Node.js", "Elastic Distribution of OpenTelemetry Node.js", VersioningSystemId.EdotNode, pa.EdotNode)
+		@RenderProduct("APM Agent Node.js", "Application Performance Monitoring Agent for Node.js", VersioningSystemId.ApmAgentNode, pa.ApmAgentNode)
 	}
 
-	if (pa.EdotPhp is not null)
+	if (pa.ApmAgentPhp is not null)
 	{
-		@RenderProduct("EDOT PHP", "Elastic Distribution of OpenTelemetry PHP", VersioningSystemId.ApmAgentPhp, pa.EdotPhp)
+		@RenderProduct("APM Agent PHP", "Application Performance Monitoring Agent for PHP", VersioningSystemId.ApmAgentPhp, pa.ApmAgentPhp)
 	}
 
-	if (pa.EdotPython is not null)
+	if (pa.ApmAgentPython is not null)
 	{
-		@RenderProduct("EDOT Python", "Elastic Distribution of OpenTelemetry Python", VersioningSystemId.EdotPython, pa.EdotPython)
+		@RenderProduct("APM Agent Python", "Application Performance Monitoring Agent for Python", VersioningSystemId.ApmAgentPython, pa.ApmAgentPython)
 	}
 
-	if (pa.EdotCfAws is not null)
+	if (pa.ApmAgentRuby is not null)
 	{
-		@RenderProduct("EDOT CF AWS", "Elastic Distribution of OpenTelemetry Cloud Forwarder for AWS", VersioningSystemId.EdotCfAws, pa.EdotCfAws)
+		@RenderProduct("APM Agent Ruby", "Application Performance Monitoring Agent for Ruby", VersioningSystemId.ApmAgentRuby, pa.ApmAgentRuby)
 	}
 
-	if (pa.EdotCollector is not null)
+	if (pa.ApmAgentRum is not null)
 	{
-		@RenderProduct("EDOT Collector", "Elastic Distribution of OpenTelemetry Collector", VersioningSystemId.EdotCollector, pa.EdotCollector)
+		@RenderProduct("APM Agent RUM", "Application Performance Monitoring Agent for Real User Monitoring", VersioningSystemId.ApmAgentRum, pa.ApmAgentRum)
 	}
 }
+@if (appliesTo.Product is not null)
+{
+	@RenderProduct("", "", VersioningSystemId.All, appliesTo.Product)
+}
 
 @functions {
 

tests/authoring/Applicability/AppliesToFrontMatter.fs

@@ -214,6 +214,55 @@ applies_to:
     let ``does not render label`` () =
         markdown |> appliesTo (Unchecked.defaultof<ApplicableTo>)
 
+type ``parses applies_to with multiple categories in any order`` () =
+    static let markdown = frontMatter """
+applies_to:
+   product: ga
+   deployment:
+      eck: ga 9.0
+   serverless:
+      security: ga 9.0.0
+   stack: ga 9.1
+   ecctl: ga 10.0
+   apm_agent_dotnet: ga 9.0
+"""
+    [<Fact>]
+    let ``parses all categories regardless of YAML order`` () =
+        markdown |> appliesTo (ApplicableTo(
+            Stack=AppliesCollection.op_Explicit "ga 9.1",
+            Serverless=ServerlessProjectApplicability(
+                Security=AppliesCollection.op_Explicit "ga 9.0.0"
+            ),
+            Deployment=DeploymentApplicability(
+                Eck=AppliesCollection.op_Explicit "ga 9.0"
+            ),
+            ProductApplicability=ProductApplicability(
+                Ecctl=AppliesCollection.op_Explicit "ga 10.0",
+                ApmAgentDotnet=AppliesCollection.op_Explicit "ga 9.0"
+            ),
+            Product=AppliesCollection.op_Explicit "ga"
+        ))
+
+type ``deployment types are rendered in correct order`` () =
+    static let markdown = frontMatter """
+applies_to:
+   deployment:
+      self: ga 9.0
+      ece: ga 9.1
+      ess: ga 9.2
+      eck: ga 9.3
+"""
+    [<Fact>]
+    let ``deployment types are rendered in ESS ECK ECE Self order`` () =
+        markdown |> appliesTo (ApplicableTo(
+            Deployment=DeploymentApplicability(
+                Ess=AppliesCollection.op_Explicit "ga 9.2",
+                Eck=AppliesCollection.op_Explicit "ga 9.3",
+                Ece=AppliesCollection.op_Explicit "ga 9.1",
+                Self=AppliesCollection.op_Explicit "ga 9.0"
+            )
+        ))
+
 type ``sorts applies_to versions in descending order`` () =
     static let markdown = frontMatter """
 applies_to: