diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap b/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap index 29dd570e2366..63430fd3632c 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/generator.test.ts.snap +++ b/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", 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 index 2bb401457537..de104a1a254a 100644 --- 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 index 8186601285a0..6620705ff712 100644 --- 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 index 0edf909bb9c8..20383b003ac8 100644 --- 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 index 3ec8a6f48124..b5cdc34aa913 100644 --- 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 index 555a2b471843..9dbd23415d3f 100644 --- 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 index e65eb41960f3..33492dc309c7 100644 --- 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({ 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 index 8d0c8da76ae0..7166d0a75525 100644 --- 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 index c6f7ca8d5ba9..1e37a44d7c90 100644 --- 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', },