Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 48 additions & 7 deletions packages/app-web-docs/sidebarItemsGenerator.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -70,6 +64,53 @@ 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 && docsById.get(docId)?.sidebarPosition != null;
}

function sortByLabel(
items: NormalizedSidebarItem[],
): NormalizedSidebarItem[] {
const normalizedItems = items.map((item): NormalizedSidebarItem =>
item.type === "category"
? { ...item, items: sortByLabel(item.items) }
Comment on lines +77 to +82

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Add tests for recursive sidebar ordering

This introduces recursive sorting and explicit-position preservation for both autogenerated sidebars, but the commit adds no test that exercises the generator; a repo-wide search finds only the implementation and its Docusaurus configuration reference. Add focused tests covering nested label ordering and preservation of sidebarPosition, so future changes cannot silently reorder the published navigation while the site still builds successfully.

AGENTS.md reference: AGENTS.md:L48-L48

Useful? React with 👍 / 👎.

: 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(),
Expand Down
Loading