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

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>

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 `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` 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
@@ -31,6 +31,7 @@ type SidebarItemDoc =
       id: string;
       label: string; // Sidebar label text
       className?: string; // Class name for sidebar label
+      customProps?: Record<string, unknown>; // Custom props
     }
 
   // Shorthand syntax
@@ -46,20 +47,20 @@ module.exports = {
     // highlight-start
     {
       type: 'doc',
-      id: 'doc1', // document id
+      id: 'doc1', // document ID
       label: 'Getting started', // sidebar label
     },
     // highlight-end
 
     // Shorthand syntax:
     // highlight-start
-    'doc2', // document id
+    'doc2', // document ID
     // highlight-end
   ],
 };
 ```
 
-If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item.
+If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page.
 
 :::note
 
@@ -67,6 +68,12 @@ A `doc` item sets an [implicit sidebar association](#sidebar-association). Don't
 
 :::
 
+:::tip
+
+Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object.
+
+:::
+
 ## Link: link to any page {#sidebar-item-link}
 
 Use the `link` type to link to any page (internal or external) that is not a doc.