From b0b3e85e057a423832940220c60fa15e36628603 Mon Sep 17 00:00:00 2001
From: mrbobbytables <mrbobbytables@users.noreply.github.com>
Date: Thu, 29 Oct 2026 20:35:08 +0000
Subject: [PATCH] fix: align User Groups sidebar with hub order

Assign unique alphabetical sidebar positions and guard numeric positions, duplicates, and agreement with the hub page.

Hive-Run: cncf/endusers#1997
Hive-Plan: user-groups-sidebar-order
Hive-Spec: issue-1997#recommendation-1
Hive-Spec: issue-1997#recommendation-2
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Signed-off-by: mrbobbytables <mrbobbytables@users.noreply.github.com>
---
 .../user-groups/public-sector/index.md        |  2 +-
 docs/community/user-groups/research/index.md  |  2 +-
 docs/community/user-groups/telecom/index.md   |  2 +-
 tests/community-group-coverage.test.mjs       | 54 +++++++++++++++++++
 4 files changed, 57 insertions(+), 3 deletions(-)

diff --git a/docs/community/user-groups/public-sector/index.md b/docs/community/user-groups/public-sector/index.md
index 18b7d83a..c4543c8b 100644
--- a/docs/community/user-groups/public-sector/index.md
+++ b/docs/community/user-groups/public-sector/index.md
@@ -1,6 +1,6 @@
 ---
 title: Public Sector
-sidebar_position: 1
+sidebar_position: 2
 description: Cloud native collaboration for public-sector end users.
 slug: /community/user-groups/public-sector
 ---
diff --git a/docs/community/user-groups/research/index.md b/docs/community/user-groups/research/index.md
index 81015456..7cd13671 100644
--- a/docs/community/user-groups/research/index.md
+++ b/docs/community/user-groups/research/index.md
@@ -1,6 +1,6 @@
 ---
 title: Research
-sidebar_position: 4
+sidebar_position: 3
 description: Research cloud native collaboration for scientific workloads.
 slug: /community/user-groups/research
 ---
diff --git a/docs/community/user-groups/telecom/index.md b/docs/community/user-groups/telecom/index.md
index 1d6bbe73..3ef2f05f 100644
--- a/docs/community/user-groups/telecom/index.md
+++ b/docs/community/user-groups/telecom/index.md
@@ -1,6 +1,6 @@
 ---
 title: Telecom
-sidebar_position: 2
+sidebar_position: 4
 description: Cloud native collaboration for telecom end users.
 slug: /community/user-groups/telecom
 ---
diff --git a/tests/community-group-coverage.test.mjs b/tests/community-group-coverage.test.mjs
index a257e65f..c61b911a 100644
--- a/tests/community-group-coverage.test.mjs
+++ b/tests/community-group-coverage.test.mjs
@@ -64,3 +64,57 @@ test('each status entry names the repository its page links', () => {
     );
   }
 });
+
+function hubOrder() {
+  const hub = readFileSync(join(pagesDir, 'index.md'), 'utf8');
+  return [...hub.matchAll(/\]\(\/community\/user-groups\/([a-z0-9-]+)\)/g)].map(
+    (match) => match[1],
+  );
+}
+
+function sidebarOrder() {
+  return pages()
+    .map((page) => ({
+      slug: page.slug,
+      position: Number(
+        /^sidebar_position:\s*(\d+)\s*$/m.exec(page.body)?.[1] ?? NaN,
+      ),
+    }))
+    .sort((a, b) => a.position - b.position || a.slug.localeCompare(b.slug))
+    .map((entry) => entry.slug);
+}
+
+test('every User Group page declares a numeric sidebar_position', () => {
+  const missing = pages()
+    .filter((page) => !/^sidebar_position:\s*\d+\s*$/m.test(page.body))
+    .map((page) => page.file);
+
+  assert.deepEqual(
+    missing,
+    [],
+    `${missing.join(', ')} needs a numeric frontmatter sidebar_position; without one Docusaurus appends the page after the ordered ones`,
+  );
+});
+
+test('no two User Group pages share a sidebar_position', () => {
+  const positions = pages().map((page) =>
+    Number(/^sidebar_position:\s*(\d+)\s*$/m.exec(page.body)?.[1] ?? NaN),
+  );
+  const duplicated = positions.filter(
+    (position, index) => positions.indexOf(position) !== index,
+  );
+
+  assert.deepEqual(
+    duplicated,
+    [],
+    `sidebar_position ${duplicated.join(', ')} is declared by more than one page under docs/community/user-groups/; ties fall back to the source path, so the menu order stops being the one the frontmatter states`,
+  );
+});
+
+test('the sidebar orders the User Groups the way the hub page lists them', () => {
+  assert.deepEqual(
+    sidebarOrder(),
+    hubOrder(),
+    'the sidebar_position values under docs/community/user-groups/ order the groups differently from the list on docs/community/user-groups/index.md; readers see one order in the menu and another on the page',
+  );
+});