Automate ordering of applies-switch tabs and badges

[Copilot]

Writers must manually order applies-switch tabs and badges according to documentation standards (serverless first, stack latest-to-oldest, specific deployment order). This is error-prone and inconsistent.

Changes

Core sorting logic (src/Elastic.Documentation/AppliesTo/ApplicableToOrderComparer.cs)

• New IComparer<ApplicableTo?> implementing standard ordering:
  • Serverless → Stack (descending version) → Deployment → Other
  • Deployment suborder: ECH/ESS → ECE → ECK → Self-managed
  • Unavailable lifecycle forced to end

Automatic tab ordering (src/Elastic.Markdown/Myst/Directives/AppliesSwitch/AppliesSwitchBlock.cs)

• FinalizeAndValidate() now sorts applies-item children via SortAppliesItems()
• Indices recalculated post-sort to maintain tab state

Badge ordering (src/Elastic.Markdown/Myst/Components/ApplicableToViewModel.cs)

• GetApplicabilityItems() orders badges with unavailable last
• Deployment mappings reordered to match standard

Tests

• 3 new test classes validating ordering scenarios
• Updated F# authoring tests for new badge order

Documentation (docs/syntax/applies-switch.md, docs/syntax/applies.md)

• Added "Automatic ordering" section to applies-switch.md explaining ordering rules with examples
• Updated "Rendering order" section in applies.md to reflect the new automatic ordering
• Added cross-references between documentation pages

Example

Before (manual ordering required):

:::::{applies-switch}
::::{applies-item} stack: ga 8.11
Old version
::::
::::{applies-item} serverless: ga
Should be first
::::
::::{applies-item} stack: preview 9.1
Newer version
::::
:::::

After (automatic reordering):
Renders as: Serverless → Stack 9.1 → Stack 8.11

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature Request]: automate ordering of applies-switch tabs and badges</issue_title>
<issue_description>### Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

Right now we render tabs as they are ordered in source files. While this is a best practice communicated to writers to order tabs (and also lists) a certain way for version and deployment related cases, it's not easy to enforce it. If possible, we should automate this whenever possible to increase the consistency of our docs

Proposed Solution

The ideal ordering is as follows:

• For versions: serverless first, then stack from latest to oldest
• for deployments: serverless first, then ech (ess), then ece, then eck, then self-managed

I think this is possible to control:

• in applies-switch components to order the tabs, knowing that this component should be used for all cases that concern versions and deployments tabbed content.
• for ordering badges inside of the same applies-switch tab (in case of multiple values)
• for ordering badges at the top of pages and at section levels

If you think this is applicable to bullet lists as well, that would be nice too.

Exceptions: "unavailable" applies_to should be last. We shouldn't have many (or even any) occurrences given our current approach, but that's just to be safe, as well as if we want to reuse this logic to determine the ordering of badges at the page and section levels.

Examples and Research

No response

Alternative Solutions

No response

Additional Context

No response

How important is this feature to you?

Important</issue_description>

<agent_instructions>ignore bullet lists for now, based on the description. that will be done in a follow-up</agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [Feature Request]: automate ordering of applies-switch tabs and badges #2424

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

Label error. Requires exactly 1 of: automation, breaking, bug, changelog:skip, chore, ci, dependencies, documentation, enhancement, feature, fix, redesign. Found:

[reakaleek]

@copilot Also reflect these changes in the appropriate docs

[Copilot]

@copilot Also reflect these changes in the appropriate docs

Documentation has been updated in commit 4cc5445:

• docs/syntax/applies-switch.md: Added "Automatic ordering" section with ordering rules and examples
• docs/syntax/applies.md: Updated "Rendering order" section to reflect serverless-first ordering

Both files now explain the automatic ordering feature with clear examples showing how tabs reorder regardless of source file order.

[github-actions]

🔍 Preview links for changed docs

• docs/syntax/applies-switch.md
• docs/syntax/applies.md