feat(content-docs): allow custom props through _category_.json (#6780)

* feat(content-docs): allow custom props through _category_.json

* refactor

* documentation

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

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

@@ -126,7 +126,12 @@ describe('DefaultSidebarItemsGenerator', () => {
         contentPath: '',
       },
       categoriesMetadata: {
-        '02-Guides': {collapsed: false},
+        '02-Guides': {
+          collapsed: false,
+          customProps: {
+            description: 'foo',
+          },
+        },
         '02-Guides/01-SubGuides': {
           label: 'SubGuides (metadata file label)',
           link: {
@@ -230,6 +235,9 @@ describe('DefaultSidebarItemsGenerator', () => {
           type: 'doc',
           id: 'guides-index',
         },
+        customProps: {
+          description: 'foo',
+        },
         collapsed: false,
         items: [
           {type: 'doc', id: 'guide1', className: 'foo'},

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

@@ -159,6 +159,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       const categoryMetadata =
         categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
       const className = categoryMetadata?.className;
+      const customProps = categoryMetadata?.customProps;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
       const allItems = Object.entries(dir).map(([key, content]) =>
         dirToItem(content, key, `${fullPath}/${key}`),
@@ -219,6 +220,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         collapsed: categoryMetadata?.collapsed,
         position: categoryMetadata?.position ?? numberPrefix,
         source: folderName,
+        ...(customProps !== undefined && {customProps}),
         ...(className !== undefined && {className}),
         items,
         ...(link && {link}),

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

@@ -216,6 +216,7 @@ export type CategoryMetadataFile = {
   collapsible?: boolean;
   className?: string;
   link?: SidebarItemCategoryLinkConfig | null;
+  customProps?: Record<string, unknown>;
 
   // TODO should we allow "items" here? how would this work? would an
   // "autogenerated" type be allowed?

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

@@ -164,6 +164,7 @@ const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
   collapsible: Joi.boolean(),
   className: Joi.string(),
   link: sidebarItemCategoryLinkSchema,
+  customProps: Joi.object().unknown(),
 });
 
 export function validateCategoryMetadataFile(

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

@@ -338,6 +338,9 @@ This is the easy tutorial!
   "link": {
     "type": "generated-index",
     "title": "Tutorial overview"
+  },
+  "customProps": {
+    "description": "This description can be used in the swizzled DocCard"
   }
 }
 ```
@@ -354,6 +357,8 @@ className: red
 link:
   type: generated-index
   title: Tutorial overview
+customProps:
+  description: This description can be used in the swizzled DocCard
 ```
 
 </TabItem>