docs: improve sidebar items custom props docs (#8888)

website/docs/api/plugins/plugin-content-docs.mdx

@@ -277,7 +277,7 @@ Accepted fields:
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
-| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
+| `sidebar_custom_props` | `object` | `undefined` | Assign [custom props](../../guides/docs/sidebar/index.mdx#passing-custom-props) to the sidebar item referencing this doc |
 | `displayed_sidebar` | `string` | `undefined` | Force the display of a given sidebar when browsing the current document. Read the [multiple sidebars guide](../../guides/docs/sidebar/multiple-sidebars.mdx) for details. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/docs/guides/docs/sidebar/index.mdx

@@ -156,15 +156,18 @@ module.exports = {
 
 ## Passing custom props {#passing-custom-props}
 
-To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
+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.
 
 ```js
 {
   type: 'doc',
   id: 'doc1',
+  // highlight-start
   customProps: {
-    /* props */
+    badges: ['new', 'green'],
+    featured: true,
   },
+  // highlight-end
 };
 ```
 

website/src/components/APITable/index.tsx

@@ -46,8 +46,12 @@ function APITableRow(
       id={id}
       tabIndex={0}
       ref={history.location.hash === anchor ? ref : undefined}
-      onClick={() => {
+      onClick={(e) => {
-        history.push(anchor);
+        const isLinkClick =
+          (e.target as HTMLElement).tagName.toUpperCase() === 'A';
+        if (!isLinkClick) {
+          history.push(anchor);
+        }
       }}
       onKeyDown={(e: React.KeyboardEvent) => {
         if (e.key === 'Enter') {

website/versioned_docs/version-2.0.1/api/plugins/plugin-content-docs.mdx

@@ -273,7 +273,7 @@ Accepted fields:
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
-| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
+| `sidebar_custom_props` | `object` | `undefined` | Assign [custom props](../../guides/docs/sidebar/index.mdx#passing-custom-props) to the sidebar item referencing this doc |
 | `displayed_sidebar` | `string` | `undefined` | Force the display of a given sidebar when browsing the current document. Read the [multiple sidebars guide](../../guides/docs/sidebar/multiple-sidebars.mdx) for details. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/versioned_docs/version-2.0.1/guides/docs/sidebar/index.mdx

@@ -157,15 +157,18 @@ module.exports = {
 
 ## Passing custom props {#passing-custom-props}
 
-To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
+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.
 
 ```js
 {
   type: 'doc',
   id: 'doc1',
+  // highlight-start
   customProps: {
-    /* props */
+    badges: ['new', 'green'],
+    featured: true,
   },
+  // highlight-end
 };
 ```
 

website/versioned_docs/version-2.1.0/api/plugins/plugin-content-docs.mdx

@@ -275,7 +275,7 @@ Accepted fields:
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
-| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
+| `sidebar_custom_props` | `object` | `undefined` | Assign [custom props](../../guides/docs/sidebar/index.mdx#passing-custom-props) to the sidebar item referencing this doc |
 | `displayed_sidebar` | `string` | `undefined` | Force the display of a given sidebar when browsing the current document. Read the [multiple sidebars guide](../../guides/docs/sidebar/multiple-sidebars.mdx) for details. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/versioned_docs/version-2.1.0/guides/docs/sidebar/index.mdx

@@ -156,15 +156,18 @@ module.exports = {
 
 ## Passing custom props {#passing-custom-props}
 
-To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
+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.
 
 ```js
 {
   type: 'doc',
   id: 'doc1',
+  // highlight-start
   customProps: {
-    /* props */
+    badges: ['new', 'green'],
+    featured: true,
   },
+  // highlight-end
 };
 ```
 

website/versioned_docs/version-2.2.0/api/plugins/plugin-content-docs.mdx

@@ -275,7 +275,7 @@ Accepted fields:
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
-| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
+| `sidebar_custom_props` | `object` | `undefined` | Assign [custom props](../../guides/docs/sidebar/index.mdx#passing-custom-props) to the sidebar item referencing this doc |
 | `displayed_sidebar` | `string` | `undefined` | Force the display of a given sidebar when browsing the current document. Read the [multiple sidebars guide](../../guides/docs/sidebar/multiple-sidebars.mdx) for details. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/versioned_docs/version-2.2.0/guides/docs/sidebar/index.mdx

@@ -156,15 +156,18 @@ module.exports = {
 
 ## Passing custom props {#passing-custom-props}
 
-To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
+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.
 
 ```js
 {
   type: 'doc',
   id: 'doc1',
+  // highlight-start
   customProps: {
-    /* props */
+    badges: ['new', 'green'],
+    featured: true,
   },
+  // highlight-end
 };
 ```
 

website/versioned_docs/version-2.3.1/api/plugins/plugin-content-docs.mdx

@@ -275,7 +275,7 @@ Accepted fields:
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
-| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
+| `sidebar_custom_props` | `object` | `undefined` | Assign [custom props](../../guides/docs/sidebar/index.mdx#passing-custom-props) to the sidebar item referencing this doc |
 | `displayed_sidebar` | `string` | `undefined` | Force the display of a given sidebar when browsing the current document. Read the [multiple sidebars guide](../../guides/docs/sidebar/multiple-sidebars.mdx) for details. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/versioned_docs/version-2.3.1/guides/docs/sidebar/index.mdx

@@ -156,15 +156,18 @@ module.exports = {
 
 ## Passing custom props {#passing-custom-props}
 
-To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
+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.
 
 ```js
 {
   type: 'doc',
   id: 'doc1',
+  // highlight-start
   customProps: {
-    /* props */
+    badges: ['new', 'green'],
+    featured: true,
   },
+  // highlight-end
 };
 ```
 

website/versioned_docs/version-2.4.0/api/plugins/plugin-content-docs.mdx

@@ -275,7 +275,7 @@ Accepted fields:
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
-| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
+| `sidebar_custom_props` | `object` | `undefined` | Assign [custom props](../../guides/docs/sidebar/index.mdx#passing-custom-props) to the sidebar item referencing this doc |
 | `displayed_sidebar` | `string` | `undefined` | Force the display of a given sidebar when browsing the current document. Read the [multiple sidebars guide](../../guides/docs/sidebar/multiple-sidebars.mdx) for details. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |

website/versioned_docs/version-2.4.0/guides/docs/sidebar/index.mdx

@@ -156,15 +156,18 @@ module.exports = {
 
 ## Passing custom props {#passing-custom-props}
 
-To pass in custom props to a swizzled sidebar item, add the optional `customProps` object to any of the items:
+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.
 
 ```js
 {
   type: 'doc',
   id: 'doc1',
+  // highlight-start
   customProps: {
-    /* props */
+    badges: ['new', 'green'],
+    featured: true,
   },
+  // highlight-end
 };
 ```