feat(content-docs): add support for sidebar item category/link descriptions in generated index page

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 & {
@@ -59,7 +60,10 @@ type SidebarItemCategoryBase = SidebarItemBase & {
   collapsible: boolean;
 };
 
-export type SidebarItemCategoryLinkDoc = {type: 'doc'; id: string};
+export type SidebarItemCategoryLinkDoc = {
+  type: 'doc';
+  id: string;
+};
 
 export type SidebarItemCategoryLinkGeneratedIndexConfig = {
   type: 'generated-index';
@@ -69,6 +73,7 @@ export type SidebarItemCategoryLinkGeneratedIndexConfig = {
   image?: string;
   keywords?: string | readonly string[];
 };
+
 export type SidebarItemCategoryLinkGeneratedIndex = {
   type: 'generated-index';
   slug: string;
@@ -92,6 +97,7 @@ export type SidebarItemCategoryConfig = Expand<
   Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: SidebarCategoriesShorthand | SidebarItemConfig[];
     link?: SidebarItemCategoryLinkConfig;
+    description?: string;
   }
 >;
 
@@ -183,6 +189,7 @@ export type PropSidebarItemCategory = Expand<
   SidebarItemCategoryBase & {
     items: PropSidebarItem[];
     href?: string;
+    description?: string;
   }
 >;
 

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

@@ -63,6 +63,9 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
   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<SidebarItemCategoryLink>()
@@ -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<SidebarItemConfig>().when('.type', {

packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx

@@ -78,19 +78,21 @@ function CardCategory({
     return null;
   }
 
+  console.log(item);
+
   return (
     <CardLayout
       href={href}
       icon="🗃️"
       title={item.label}
       description={translate(
         {
-          message: '{count} items',
+          message: '({count} items) {description}',
           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 ?? '', count: item.items.length},
       )}
     />
   );
@@ -104,7 +106,9 @@ function CardLink({item}: {item: PropSidebarItemLink}): JSX.Element {
       href={item.href}
       icon={icon}
       title={item.label}
-      description={doc?.description}
+      description={
+        isInternalUrl(item.href) ? doc?.description : item.description
+      }
     />
   );
 }

website/_dogfooding/docs-tests-sidebars.js

@@ -39,6 +39,12 @@ const sidebars = {
           label: 'External Link test',
           href: 'https://docusaurus.io',
         },
+        {
+          type: 'link',
+          label: 'External Link with description',
+          href: 'https://docusaurus.io',
+          description: 'Some description',
+        },
       ],
     },
     {