diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts index d6d7f07a7587..0aa9a4d5ff1b 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/types.ts @@ -45,6 +45,7 @@ export type SidebarItemLink = SidebarItemBase & { href: string; label: string; autoAddBaseUrl?: boolean; + description?: string; }; export type SidebarItemAutogenerated = SidebarItemBase & { @@ -57,6 +58,7 @@ type SidebarItemCategoryBase = SidebarItemBase & { label: string; collapsed: boolean; collapsible: boolean; + description?: string; }; export type SidebarItemCategoryLinkDoc = {type: 'doc'; id: string}; diff --git a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts index 0273132360d1..e65eb41960f3 100644 --- a/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts +++ b/packages/docusaurus-plugin-content-docs/src/sidebars/validation.ts @@ -63,6 +63,9 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append({ label: Joi.string() .required() .messages({'any.unknown': '"label" must be a string'}), + description: Joi.string().optional().messages({ + 'any.unknown': '"description" must be a string', + }), }); const sidebarItemCategoryLinkSchema = Joi.object() @@ -116,6 +119,9 @@ const sidebarItemCategorySchema = collapsible: Joi.boolean().messages({ 'any.unknown': '"collapsible" must be a boolean', }), + description: Joi.string().optional().messages({ + 'any.unknown': '"description" must be a string', + }), }); const sidebarItemSchema = Joi.object().when('.type', { diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx index c486df8de2a3..9e1b190d266c 100644 --- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx +++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx @@ -87,15 +87,18 @@ function CardCategory({ href={href} icon="🗃️" title={item.label} - description={translate( - { - message: '{count} items', - id: 'theme.docs.DocCard.categoryDescription', - description: - 'The default description for a category card in the generated index about how many items this category includes', - }, - {count: item.items.length}, - )} + description={ + item.description ?? + translate( + { + message: '{count} items', + id: 'theme.docs.DocCard.categoryDescription', + description: + 'The default description for a category card in the generated index about how many items this category includes', + }, + {count: item.items.length}, + ) + } /> ); } @@ -108,7 +111,7 @@ function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element { href={item.href} icon={icon} title={item.label} - description={doc?.description} + description={item.description ?? doc?.description} /> ); } diff --git a/website/_dogfooding/docs-tests-sidebars.js b/website/_dogfooding/docs-tests-sidebars.js index add2433e77b8..c6f7ca8d5ba9 100644 --- a/website/_dogfooding/docs-tests-sidebars.js +++ b/website/_dogfooding/docs-tests-sidebars.js @@ -38,6 +38,49 @@ const sidebars = { label: 'External Link test', href: 'https://docusaurus.io', }, + { + type: 'category', + label: 'Sidebar item description tests', + link: { + type: 'generated-index', + }, + items: [ + { + type: 'link', + label: 'Link without description', + href: 'https://docusaurus.io', + }, + { + type: 'link', + label: 'Link with description', + href: 'https://docusaurus.io', + description: 'Some link description', + }, + { + type: 'category', + label: 'Category without description', + items: [ + { + type: 'link', + label: 'Link ', + href: 'https://docusaurus.io', + }, + ], + }, + { + type: 'category', + label: 'Category with description', + description: 'Some category description', + items: [ + { + type: 'link', + label: 'Link ', + href: 'https://docusaurus.io', + }, + ], + }, + ], + }, ], }, { diff --git a/website/docs/guides/docs/sidebar/items.mdx b/website/docs/guides/docs/sidebar/items.mdx index b2793826f98b..1e358a12fee6 100644 --- a/website/docs/guides/docs/sidebar/items.mdx +++ b/website/docs/guides/docs/sidebar/items.mdx @@ -85,6 +85,7 @@ type SidebarItemLink = { label: string; href: string; className?: string; + description?: string; }; ``` @@ -173,6 +174,7 @@ type SidebarItemCategory = { label: string; // Sidebar label text. items: SidebarItem[]; // Array of sidebar items. className?: string; + description?: string; // Category options: collapsible: boolean; // Set the category to be collapsible diff --git a/website/docs/guides/docs/sidebar/multiple-sidebars.mdx b/website/docs/guides/docs/sidebar/multiple-sidebars.mdx index e90ba26a98ac..419a8fc57258 100644 --- a/website/docs/guides/docs/sidebar/multiple-sidebars.mdx +++ b/website/docs/guides/docs/sidebar/multiple-sidebars.mdx @@ -116,7 +116,7 @@ The pagination label by default is the sidebar label. You can use the front matt ## The `ref` item {#sidebar-item-ref} -The `ref` type is identical to the [`doc` type](#sidebar-item-doc) in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When [generating pagination](#generating-pagination) and [displaying sidebar](#sidebar-association), `ref` items are completely ignored. +The `ref` type is identical to the [`doc` type](./items.mdx#sidebar-item-doc) in every way, except that it doesn't participate in generating navigation metadata. It only registers itself as a link. When [generating pagination](#generating-pagination) and [displaying sidebar](#sidebar-association), `ref` items are completely ignored. It is particularly useful where you wish to link to the same document from multiple sidebars. The document only belongs to one sidebar (the one where it's registered as `type: 'doc'` or from an autogenerated directory), but its link will appear in all sidebars that it's registered in.