fix(docs): the _category_.json description attribute should display o…

…n generated index pages (#10324) Co-authored-by: sebastien <[email protected]>
facebook · Aug 9, 2024 · 44ddada · 44ddada
1 parent 95ab9f8
commit 44ddada
Show file tree

Hide file tree

Showing 9 changed files with 11 additions and 0 deletions.
diff --git a/...ocusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap b/...ocusaurus-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",

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/generator.test.ts b/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

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/validation.test.ts b/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',

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/generator.ts b/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}),
       };
     }

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/postProcessor.ts b/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) {

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/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;

diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/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(),

diff --git a/website/_dogfooding/_docs tests/tests/category-links/_category_.json b/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"

diff --git a/website/_dogfooding/docs-tests-sidebars.js b/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',
           },