feat(v2): add custom props for consumption by swizzled sidebar (#3888)

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

@@ -361,6 +361,7 @@ describe('transformSidebarItems', () => {
             collapsed: false,
             label: 'Subcategory 1',
             items: [{type: 'doc', id: 'doc1'}],
+            customProps: {fakeProp: false},
           },
           {
             type: 'category',
@@ -372,7 +373,9 @@ describe('transformSidebarItems', () => {
                 type: 'category',
                 collapsed: false,
                 label: 'Sub sub category 1',
-                items: [{type: 'doc', id: 'doc3'}],
+                items: [
+                  {type: 'doc', id: 'doc3', customProps: {lorem: 'ipsum'}},
+                ],
               },
             ],
           },
@@ -407,6 +410,7 @@ describe('transformSidebarItems', () => {
             collapsed: false,
             label: 'MODIFIED LABEL: Subcategory 1',
             items: [{type: 'doc', id: 'doc1'}],
+            customProps: {fakeProp: false},
           },
           {
             type: 'category',
@@ -418,7 +422,9 @@ describe('transformSidebarItems', () => {
                 type: 'category',
                 collapsed: false,
                 label: 'MODIFIED LABEL: Sub sub category 1',
-                items: [{type: 'doc', id: 'doc3'}],
+                items: [
+                  {type: 'doc', id: 'doc3', customProps: {lorem: 'ipsum'}},
+                ],
               },
             ],
           },

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

@@ -21,13 +21,17 @@ declare module '@docusaurus/plugin-content-docs-types' {
     permalinkToSidebar: PermalinkToSidebar;
   };
 
-  export type PropSidebarItemLink = {
+  type PropsSidebarItemBase = {
+    customProps?: object;
+  };
+
+  export type PropSidebarItemLink = PropsSidebarItemBase & {
     type: 'link';
     href: string;
     label: string;
   };
 
-  export type PropSidebarItemCategory = {
+  export type PropSidebarItemCategory = PropsSidebarItemBase & {
     type: 'category';
     label: string;
     items: PropSidebarItem[];

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

@@ -39,6 +39,7 @@ Available document ids=
       type: 'link',
       label: sidebar_label || title,
       href: permalink,
+      customProps: item.customProps,
     };
   };
 

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

@@ -11,6 +11,7 @@ import importFresh from 'import-fresh';
 import {
   Sidebars,
   SidebarItem,
+  SidebarItemBase,
   SidebarItemLink,
   SidebarItemDoc,
   Sidebar,
@@ -20,7 +21,7 @@ import {
 import {mapValues, flatten, difference} from 'lodash';
 import {getElementsAround} from '@docusaurus/utils';
 
-type SidebarItemCategoryJSON = {
+type SidebarItemCategoryJSON = SidebarItemBase & {
   type: 'category';
   label: string;
   items: SidebarItemJSON[];
@@ -96,7 +97,7 @@ function assertItem<K extends string>(
 function assertIsCategory(
   item: unknown,
 ): asserts item is SidebarItemCategoryJSON {
-  assertItem(item, ['items', 'label', 'collapsed']);
+  assertItem(item, ['items', 'label', 'collapsed', 'customProps']);
   if (typeof item.label !== 'string') {
     throw new Error(
       `Error loading ${JSON.stringify(item)}. "label" must be a string.`,
@@ -116,7 +117,7 @@ function assertIsCategory(
 }
 
 function assertIsDoc(item: unknown): asserts item is SidebarItemDoc {
-  assertItem(item, ['id']);
+  assertItem(item, ['id', 'customProps']);
   if (typeof item.id !== 'string') {
     throw new Error(
       `Error loading ${JSON.stringify(item)}. "id" must be a string.`,
@@ -125,7 +126,7 @@ function assertIsDoc(item: unknown): asserts item is SidebarItemDoc {
 }
 
 function assertIsLink(item: unknown): asserts item is SidebarItemLink {
-  assertItem(item, ['href', 'label']);
+  assertItem(item, ['href', 'label', 'customProps']);
   if (typeof item.href !== 'string') {
     throw new Error(
       `Error loading ${JSON.stringify(item)}. "href" must be a string.`,

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

@@ -75,18 +75,22 @@ export type PluginOptions = MetadataOptions &
     includeCurrentVersion: boolean;
   };
 
-export type SidebarItemDoc = {
+export type SidebarItemBase = {
+  customProps?: object;
+};
+
+export type SidebarItemDoc = SidebarItemBase & {
   type: 'doc' | 'ref';
   id: string;
 };
 
-export type SidebarItemLink = {
+export type SidebarItemLink = SidebarItemBase & {
   type: 'link';
   href: string;
   label: string;
 };
 
-export type SidebarItemCategory = {
+export type SidebarItemCategory = SidebarItemBase & {
   type: 'category';
   label: string;
   items: SidebarItem[];

website/docs/docs.md

@@ -288,6 +288,20 @@ module.exports = {
 };
 ```
 
+#### Custom Props
+
+If you would like to pass in custom props to a swizzled sidebar item, an optional object called `customProps` can be added to any of the items:
+
+```js
+{
+  type: 'doc';
+  id: 'doc1';
+  customProps: {
+    /* props */
+  }
+}
+```
+
 #### Collapsible categories
 
 For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`: