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

Co-authored-by: Davide Donadio <davide.donadio@it.clara.net>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

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};

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

@@ -87,7 +87,9 @@ function CardCategory({
       href={href}
       icon="🗃️"
       title={item.label}
-      description={translate(
+      description={
+        item.description ??
+        translate(
           {
             message: '{count} items',
             id: 'theme.docs.DocCard.categoryDescription',
@@ -95,7 +97,8 @@ function CardCategory({
               '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}
     />
   );
 }

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',
+                },
+              ],
+            },
+          ],
+        },
       ],
     },
     {

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

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.