From d7fb90e2d68f1ca8edb4061e3167e5e9be4f4da8 Mon Sep 17 00:00:00 2001
From: sebastien <lorber.sebastien@gmail.com>
Date: Thu, 3 Jul 2025 13:11:45 +0200
Subject: [PATCH] Add docs

---
 website/docs/guides/docs/sidebar/index.mdx | 40 ++++++++++++++++++++--
 website/docs/guides/docs/sidebar/items.mdx | 15 +++++---
 2 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/website/docs/guides/docs/sidebar/index.mdx b/website/docs/guides/docs/sidebar/index.mdx
index 4d2c4d209b..307d836fb3 100644
--- a/website/docs/guides/docs/sidebar/index.mdx
+++ b/website/docs/guides/docs/sidebar/index.mdx
@@ -6,8 +6,8 @@ slug: /sidebar
 
 Creating a sidebar is useful to:
 
-- Group multiple **related documents**
-- **Display a sidebar** on each of those documents
+- Group multiple **related documents** into an ordered tree
+- **Display a common sidebar** on each of those documents
 - Provide **paginated navigation**, with next/previous button
 
 To use sidebars on your Docusaurus site:
@@ -160,6 +160,20 @@ export default {
 };
 ```
 
+## Passing CSS classes {#passing-css-classes}
+
+To pass CSS classes to a sidebar item, add the optional `className` attribute to any of the items. This is useful to apply visual customizations to specific sidebar items.
+
+```js
+{
+  type: 'doc',
+  id: 'doc1',
+  // highlight-start
+  className: 'sidebar-item--highlighted',
+  // highlight-end
+};
+```
+
 ## Passing custom props {#passing-custom-props}
 
 To pass in custom props to a sidebar item, add the optional `customProps` object to any of the items. This is useful to apply site customizations by swizzling React components rendering sidebar items.
@@ -177,6 +191,28 @@ To pass in custom props to a sidebar item, add the optional `customProps` object
 };
 ```
 
+## Passing a unique key {#passing-custom-props}
+
+Passing a unique `key` attribute can help uniquely identify a sidebar item. Sometimes other attributes (such as `label`) are not enough to distinguish two sidebar items from each other.
+
+```js
+{
+  type: 'category',
+  // highlight-start
+  label: 'API', // You may have multiple categories with this widespread label
+  key: 'api-for-feature-1', // and now, they can be uniquely identified
+  // highlight-end
+};
+```
+
+:::info How is this useful?
+
+Docusaurus only uses the `key` attribute to generate unique i18n translation keys. When a translation key conflict happens ([issue](https://github.com/facebook/docusaurus/issues/10913)), Docusaurus will tell you to apply a `key` to distinguish sidebar items.
+
+Alternatively, you may have your own reasons for using the `key` attribute that will be passed to the respective sidebar item React components.
+
+:::
+
 ## Sidebar Breadcrumbs {#sidebar-breadcrumbs}
 
 By default, breadcrumbs are rendered at the top, using the "sidebar path" of the current page.
diff --git a/website/docs/guides/docs/sidebar/items.mdx b/website/docs/guides/docs/sidebar/items.mdx
index 1dd0c0100e..12c4a518ee 100644
--- a/website/docs/guides/docs/sidebar/items.mdx
+++ b/website/docs/guides/docs/sidebar/items.mdx
@@ -11,14 +11,14 @@ import TabItem from '@theme/TabItem';
 import BrowserWindow from '@site/src/components/BrowserWindow';
 ```
 
-We have introduced three types of item types in the example in the previous section: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later.
+The sidebar supports various item types:
 
 - **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar
 - **[Link](#sidebar-item-link)**: link to any internal or external page
 - **[Category](#sidebar-item-category)**: creates a dropdown of sidebar items
 - **[Autogenerated](autogenerated.mdx)**: generate a sidebar slice automatically
 - **[HTML](#sidebar-item-html)**: renders pure HTML in the item's position
-- **[\*Ref](multiple-sidebars.mdx#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation
+- **[Ref](multiple-sidebars.mdx#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation
 
 ## Doc: link to a doc {#sidebar-item-doc}
 
@@ -31,6 +31,7 @@ type SidebarItemDoc =
       type: 'doc';
       id: string;
       label: string; // Sidebar label text
+      key?: string; // Sidebar key to uniquely identify the item
       className?: string; // Class name for sidebar label
       customProps?: Record<string, unknown>; // Custom props
     }
@@ -84,8 +85,10 @@ type SidebarItemLink = {
   type: 'link';
   label: string;
   href: string;
-  className?: string;
   description?: string;
+  key?: string;
+  className?: string;
+  customProps?: Record<string, unknown>;
 };
 ```
 
@@ -126,7 +129,9 @@ type SidebarItemHtml = {
   type: 'html';
   value: string;
   defaultStyle?: boolean; // Use default menu item styles
+  key?: string;
   className?: string;
+  customProps?: Record<string, unknown>;
 };
 ```
 
@@ -173,8 +178,10 @@ type SidebarItemCategory = {
   type: 'category';
   label: string; // Sidebar label text.
   items: SidebarItem[]; // Array of sidebar items.
-  className?: string;
   description?: string;
+  key?: string;
+  className?: string;
+  customProps?: Record<string, unknown>;
 
   // Category options:
   collapsible: boolean; // Set the category to be collapsible