diff --git a/docs/contribute/cumulative-docs/guidelines.md b/docs/contribute/cumulative-docs/guidelines.md index 05fbefb28..919208f44 100644 --- a/docs/contribute/cumulative-docs/guidelines.md +++ b/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 -% +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 -% +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] diff --git a/docs/syntax/applies.md b/docs/syntax/applies.md index e193229a7..77be6d5d7 100644 --- a/docs/syntax/applies.md +++ b/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. \ No newline at end of file diff --git a/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml b/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml index fcc8f897f..2b0517e88 100644 --- a/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml +++ b/src/Elastic.Markdown/Myst/Components/ApplicableToComponent.cshtml @@ -18,47 +18,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) @@ -103,9 +62,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) { @@ -120,101 +117,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 { diff --git a/tests/authoring/Applicability/AppliesToFrontMatter.fs b/tests/authoring/Applicability/AppliesToFrontMatter.fs index 2d4c2c9a8..89d970e69 100644 --- a/tests/authoring/Applicability/AppliesToFrontMatter.fs +++ b/tests/authoring/Applicability/AppliesToFrontMatter.fs @@ -214,6 +214,55 @@ applies_to: let ``does not render label`` () = markdown |> appliesTo (Unchecked.defaultof) +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 +""" + [] + 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 +""" + [] + 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: