fix(docs): the _category_.json description attribute should display on generated index pages (#10324)

Co-authored-by: sebastien <lorber.sebastien@gmail.com>

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

@@ -217,6 +217,7 @@ exports[`DefaultSidebarItemsGenerator uses explicit link over the index/readme.{
   {
     "collapsed": undefined,
     "collapsible": undefined,
+    "description": "Category description",
     "items": [
       {
         "id": "parent/doc2",

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

@@ -331,6 +331,7 @@ describe('DefaultSidebarItemsGenerator', () => {
       categoriesMetadata: {
         Category: {
           label: 'Category label',
+          description: 'Category description',
           link: {
             type: 'doc',
             id: 'doc3', // Using a "local doc id" ("doc1" instead of "parent/doc1") on purpose

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

@@ -282,6 +282,7 @@ describe('validateCategoryMetadataFile', () => {
     const content: CategoryMetadataFile = {
       className: 'className',
       label: 'Category Label',
+      description: 'Category Description',
       link: {
         type: 'generated-index',
         slug: 'slug',

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

@@ -249,6 +249,9 @@ Available doc IDs:
         ...(customProps !== undefined && {customProps}),
         ...(className !== undefined && {className}),
         items,
+        ...(categoryMetadata?.description && {
+          description: categoryMetadata?.description,
+        }),
         ...(link && {link}),
       };
     }

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

@@ -64,6 +64,7 @@ function postProcessSidebarItem(
         .map((subItem) => postProcessSidebarItem(subItem, params))
         .filter((v): v is SidebarItem => Boolean(v)),
     };
+
     // If the current category doesn't have subitems, we render a normal link
     // instead.
     if (category.items.length === 0) {

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

@@ -217,6 +217,7 @@ export type PropSidebarBreadcrumbsItem =
 export type CategoryMetadataFile = {
   label?: string;
   position?: number;
+  description?: string;
   collapsed?: boolean;
   collapsible?: boolean;
   className?: string;

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

@@ -167,6 +167,7 @@ export function validateSidebars(sidebars: {
 
 const categoryMetadataFileSchema = Joi.object<CategoryMetadataFile>({
   label: Joi.string(),
+  description: Joi.string(),
   position: Joi.number(),
   collapsed: Joi.boolean(),
   collapsible: Joi.boolean(),

website/_dogfooding/_docs tests/tests/category-links/_category_.json

@@ -1,5 +1,6 @@
 {
   "label": "Category Links",
+  "description": "Category Links - Custom Description",
   "link": {
     "type": "generated-index",
     "slug": "/category-links-generated-index-slug"

website/_dogfooding/docs-tests-sidebars.js

@@ -41,6 +41,7 @@ const sidebars = {
         {
           type: 'category',
           label: 'Sidebar item description tests',
+          description: 'Some custom category description',
           link: {
             type: 'generated-index',
           },