feat(content-docs): add custom props front matter

packages/docusaurus-plugin-content-docs/src/__tests__/docFrontMatter.test.ts

@@ -210,6 +210,19 @@ describe('validateDocFrontMatter sidebar_position', () => {
   });
 });
 
+describe('validateDocFrontMatter sidebar_custom_props', () => {
+  testField({
+    prefix: 'sidebar_custom_props',
+    validFrontMatters: [
+      {sidebar_custom_props: {}},
+      {sidebar_custom_props: {prop: 'custom', number: 1, boolean: true}},
+    ],
+    invalidFrontMatters: [
+      [{sidebar_custom_props: ''}, 'must be of type object'],
+    ],
+  });
+});
+
 describe('validateDocFrontMatter custom_edit_url', () => {
   testField({
     prefix: 'custom_edit_url',

packages/docusaurus-plugin-content-docs/src/docFrontMatter.ts

@@ -30,6 +30,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),
+  sidebar_custom_props: Joi.object().unknown(),
   displayed_sidebar: Joi.string().allow(null),
   tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),

packages/docusaurus-plugin-content-docs/src/props.ts

@@ -52,7 +52,8 @@ Available document ids are:
       label: sidebarLabel || item.label || title,
       href: permalink,
       className: item.className,
-      customProps: item.customProps,
+      customProps:
+        item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
       docId: docMetadata.unversionedId,
     };
   };

packages/docusaurus-plugin-content-docs/src/types.ts

@@ -58,6 +58,7 @@ export type DocFrontMatter = {
   sidebar_label?: string;
   sidebar_position?: number;
   sidebar_class_name?: string;
+  sidebar_custom_props?: Record<string, unknown>;
   displayed_sidebar?: string | null;
   pagination_label?: string;
   custom_edit_url?: string | null;

website/_dogfooding/_docs tests/tests/custom-props/_category_.json

@@ -0,0 +1,3 @@
+{
+  "label": "Custom Props"
+}

website/_dogfooding/_docs tests/tests/custom-props/doc-with-custom-props.md

@@ -0,0 +1,10 @@
+---
+sidebar_custom_props:
+  prop: custom
+  number: 1
+  boolean: true
+---
+
+# Doc with Custom Props
+
+This doc has custom props.

website/_dogfooding/_docs tests/tests/custom-props/doc-without-custom-props.md

@@ -0,0 +1,3 @@
+# Doc Without Custom Props
+
+This doc doesn't have custom props.

website/_dogfooding/_docs tests/tests/custom-props/index.md

@@ -0,0 +1,22 @@
+# Custom Props
+
+```mdx-code-block
+import {useCurrentSidebarCategory} from '@docusaurus/theme-common';
+
+export const DocPropsList = ({items}) => (
+  <table>
+    <tr>
+      <th>Doc Page</th>
+      <th>Custom Props</th>
+    </tr>
+    {items.map((item, index) => (
+      <tr>
+        <td>{item.label}</td>
+        <td>{JSON.stringify(item.customProps)}</td>
+      </tr>
+    ))}
+  </table>
+);
+
+<DocPropsList items={useCurrentSidebarCategory().items}/>
+```

website/docs/guides/docs/sidebar/autogenerated.md

@@ -305,9 +305,9 @@ function isCategoryIndex({fileName, directories}) {
 
 ## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
 
-For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
+For handwritten sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in **alphabetical order** (using file and folder names).
 
-**For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter.
+**For docs**: use additional front matter. The `position`, `label`, and `className` attributes are declared using `sidebar_position`, `sidebar_label`, and `sidebar_class_name` front matter, respectively. (Custom props can also be supplied via `sidebar_custom_props` front matter.)
 
 ```md title="docs/tutorials/tutorial-easy.md"
 ---

website/docs/guides/docs/sidebar/items.md

@@ -3,13 +3,13 @@ toc_max_heading_level: 4
 slug: /sidebar/items
 ---
 
+# Sidebar items
+
 ```mdx-code-block
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 ```
 
-# Sidebar items
-
 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.
 
 - **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar