From 179674112975883208e5a563dc9d16301a6c422d Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Fri, 27 Jun 2025 16:52:24 +0200
Subject: [PATCH] add tests for sidebar item keys props + ensure the key
 attribute is forwarded to frontend as props for all sidebar items

---
 .../src/__tests__/props.test.ts               | 127 +++++++++++++++++-
 .../src/props.ts                              |   5 +-
 2 files changed, 130 insertions(+), 2 deletions(-)

diff --git a/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts b/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts
index 960727f01f..4debd95e57 100644
--- a/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts
+++ b/packages/docusaurus-plugin-content-docs/src/__tests__/props.test.ts
@@ -5,7 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {toSidebarDocItemLinkProp, toTagDocListProp} from '../props';
+import {fromPartial} from '@total-typescript/shoehorn';
+import {
+  toSidebarDocItemLinkProp,
+  toSidebarsProp,
+  toTagDocListProp,
+} from '../props';
 
 describe('toTagDocListProp', () => {
   type Params = Parameters<typeof toTagDocListProp>[0];
@@ -132,3 +137,123 @@ describe('toSidebarDocItemLinkProp', () => {
     ).toBe(false);
   });
 });
+
+describe('toSidebarsProp', () => {
+  type Params = Parameters<typeof toSidebarsProp>[0];
+
+  it('works', () => {
+    const params: Params = {
+      docs: [
+        fromPartial({
+          id: 'doc-id-1',
+          frontMatter: {},
+        }),
+      ],
+      sidebars: {
+        mySidebar: [
+          {
+            type: 'link',
+            label: 'Example link',
+            key: 'link-example-key',
+            href: 'https://example.com',
+          },
+          {
+            type: 'ref',
+            label: 'Doc 1 ref',
+            key: 'ref-with-doc-id-1',
+            id: 'doc-id-1',
+          },
+          {
+            type: 'ref',
+            label: 'Doc 1 ref bis',
+            // no key on purpose
+            id: 'doc-id-1',
+          },
+          {
+            type: 'category',
+            label: 'My category',
+            key: 'my-category-key',
+            collapsible: false,
+            collapsed: true,
+            items: [
+              {
+                type: 'doc',
+                label: 'Doc 1',
+                key: 'doc-id-1',
+                id: 'doc-id-1',
+              },
+              {
+                type: 'doc',
+                label: 'Doc 1 bis',
+                // no key on purpose
+                id: 'doc-id-1',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const result = toSidebarsProp(params);
+
+    expect(result).toMatchInlineSnapshot(`
+      {
+        "mySidebar": [
+          {
+            "href": "https://example.com",
+            "key": "link-example-key",
+            "label": "Example link",
+            "type": "link",
+          },
+          {
+            "className": undefined,
+            "customProps": undefined,
+            "docId": "doc-id-1",
+            "href": undefined,
+            "key": "ref-with-doc-id-1",
+            "label": "Doc 1 ref",
+            "type": "link",
+            "unlisted": undefined,
+          },
+          {
+            "className": undefined,
+            "customProps": undefined,
+            "docId": "doc-id-1",
+            "href": undefined,
+            "label": "Doc 1 ref bis",
+            "type": "link",
+            "unlisted": undefined,
+          },
+          {
+            "collapsed": true,
+            "collapsible": false,
+            "items": [
+              {
+                "className": undefined,
+                "customProps": undefined,
+                "docId": "doc-id-1",
+                "href": undefined,
+                "key": "doc-id-1",
+                "label": "Doc 1",
+                "type": "link",
+                "unlisted": undefined,
+              },
+              {
+                "className": undefined,
+                "customProps": undefined,
+                "docId": "doc-id-1",
+                "href": undefined,
+                "label": "Doc 1 bis",
+                "type": "link",
+                "unlisted": undefined,
+              },
+            ],
+            "key": "my-category-key",
+            "label": "My category",
+            "type": "category",
+          },
+        ],
+      }
+    `);
+  });
+});
diff --git a/packages/docusaurus-plugin-content-docs/src/props.ts b/packages/docusaurus-plugin-content-docs/src/props.ts
index 3f2d00c87c..c7a2eb1040 100644
--- a/packages/docusaurus-plugin-content-docs/src/props.ts
+++ b/packages/docusaurus-plugin-content-docs/src/props.ts
@@ -41,6 +41,7 @@ export function toSidebarDocItemLinkProp({
   const {id, title, permalink, frontMatter, unlisted} = doc;
   return {
     type: 'link',
+    ...(item.key && {key: item.key}),
     href: permalink,
     // Front Matter data takes precedence over sidebars.json
     label: frontMatter.sidebar_label ?? item.label ?? title,
@@ -51,7 +52,9 @@ export function toSidebarDocItemLinkProp({
   };
 }
 
-export function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars {
+export function toSidebarsProp(
+  loadedVersion: Pick<LoadedVersion, 'docs' | 'sidebars'>,
+): PropSidebars {
   const docsById = createDocsByIdIndex(loadedVersion.docs);
 
   function getDocById(docId: string): DocMetadata {