From adc5ed5e4c285fe9646cc1aea07237283bdedf1b Mon Sep 17 00:00:00 2001 From: Andreas Arvidsson Date: Sun, 30 Aug 2026 14:36:26 +0200 Subject: [PATCH 1/3] Sort sidebar items on label for the docs page --- .../app-web-docs/sidebarItemsGenerator.ts | 59 ++++++++++++++++--- 1 file changed, 52 insertions(+), 7 deletions(-) diff --git a/packages/app-web-docs/sidebarItemsGenerator.ts b/packages/app-web-docs/sidebarItemsGenerator.ts index ab045c213d..2c7f2c5a10 100644 --- a/packages/app-web-docs/sidebarItemsGenerator.ts +++ b/packages/app-web-docs/sidebarItemsGenerator.ts @@ -51,15 +51,9 @@ export const sidebarItemsGenerator: SidebarItemsGenerator = async ({ const generatedItems = await defaultSidebarItemsGenerator(args); type NormalizedSidebarItem = (typeof generatedItems)[number]; - - if (args.item.dirName !== "user") { - return generatedItems; - } - const docsById = new Map(args.docs.map((doc) => [doc.id, doc])); - const remainingItems = generatedItems.slice(); - function getLabel(item: (typeof generatedItems)[number]) { + function getLabel(item: NormalizedSidebarItem) { if (item.type === "doc" || item.type === "ref") { const doc = docsById.get(item.id); return doc?.frontMatter.sidebar_label ?? doc?.title; @@ -70,6 +64,57 @@ export const sidebarItemsGenerator: SidebarItemsGenerator = async ({ throw new Error(`Unexpected sidebar item type: ${item.type}`); } + function hasExplicitPosition(item: NormalizedSidebarItem): boolean { + let docId: string | undefined; + if (item.type === "doc" || item.type === "ref") { + docId = item.id; + } else if (item.type === "category" && item.link?.type === "doc") { + docId = item.link.id; + } + return ( + docId != null && + typeof docsById.get(docId)?.frontMatter.sidebar_position === "number" + ); + } + + function sortByLabel( + items: NormalizedSidebarItem[], + ): NormalizedSidebarItem[] { + const normalizedItems = items.map( + (item): NormalizedSidebarItem => + item.type === "category" + ? { ...item, items: sortByLabel(item.items) } + : item, + ); + const unpositionedItems = normalizedItems + .filter((item) => !hasExplicitPosition(item)) + .toSorted((a, b) => + (getLabel(a) ?? "").localeCompare(getLabel(b) ?? "", undefined, { + numeric: true, + sensitivity: "base", + }), + ); + + return normalizedItems.map((item) => { + if (hasExplicitPosition(item)) { + return item; + } + const sortedItem = unpositionedItems.shift(); + if (sortedItem == null) { + throw new Error("Missing unpositioned sidebar item"); + } + return sortedItem; + }); + } + + const sortedItems = sortByLabel(generatedItems); + + if (args.item.dirName !== "user") { + return sortedItems; + } + + const remainingItems = sortedItems.slice(); + function takeItem(label: string): NormalizedSidebarItem { const index = remainingItems.findIndex( (item) => getLabel(item)?.toLowerCase() === label.toLowerCase(), From ec73cf31b166e49eb72ac04580d46a1f4e9e0fd8 Mon Sep 17 00:00:00 2001 From: Andreas Arvidsson Date: Sun, 30 Aug 2026 14:40:11 +0200 Subject: [PATCH 2/3] Format --- packages/app-web-docs/sidebarItemsGenerator.ts | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/packages/app-web-docs/sidebarItemsGenerator.ts b/packages/app-web-docs/sidebarItemsGenerator.ts index 2c7f2c5a10..b98a6f8b1f 100644 --- a/packages/app-web-docs/sidebarItemsGenerator.ts +++ b/packages/app-web-docs/sidebarItemsGenerator.ts @@ -80,11 +80,10 @@ export const sidebarItemsGenerator: SidebarItemsGenerator = async ({ function sortByLabel( items: NormalizedSidebarItem[], ): NormalizedSidebarItem[] { - const normalizedItems = items.map( - (item): NormalizedSidebarItem => - item.type === "category" - ? { ...item, items: sortByLabel(item.items) } - : item, + const normalizedItems = items.map((item): NormalizedSidebarItem => + item.type === "category" + ? { ...item, items: sortByLabel(item.items) } + : item, ); const unpositionedItems = normalizedItems .filter((item) => !hasExplicitPosition(item)) From 2bb8befce89c75090fcd4ade0332910d7bfed524 Mon Sep 17 00:00:00 2001 From: Andreas Arvidsson Date: Sun, 30 Aug 2026 14:46:14 +0200 Subject: [PATCH 3/3] Use sidebarPosition --- packages/app-web-docs/sidebarItemsGenerator.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/packages/app-web-docs/sidebarItemsGenerator.ts b/packages/app-web-docs/sidebarItemsGenerator.ts index b98a6f8b1f..2eaac3dbd7 100644 --- a/packages/app-web-docs/sidebarItemsGenerator.ts +++ b/packages/app-web-docs/sidebarItemsGenerator.ts @@ -71,10 +71,7 @@ export const sidebarItemsGenerator: SidebarItemsGenerator = async ({ } else if (item.type === "category" && item.link?.type === "doc") { docId = item.link.id; } - return ( - docId != null && - typeof docsById.get(docId)?.frontMatter.sidebar_position === "number" - ); + return docId != null && docsById.get(docId)?.sidebarPosition != null; } function sortByLabel(