fix(content-docs): render category with no subitems as a normal link (#6495)

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/processor.test.ts

@@ -209,6 +209,12 @@ describe('processSidebars', () => {
           // typing error needing refactor
           permalink: undefined,
         },
+        items: [
+          {
+            type: 'doc',
+            id: 'foo',
+          },
+        ],
       },
     ];
 
@@ -232,11 +238,73 @@ describe('processSidebars', () => {
             slug: 'generated-cat-index-slug',
             permalink: '/docs/1.0.0/generated-cat-index-slug',
           },
-          items: [],
+          items: [
+            {
+              type: 'doc',
+              id: 'foo',
+            },
+          ],
           collapsible: true,
           collapsed: true,
         },
       ],
     } as Sidebars);
   });
+
+  test('transforms category without subitems', async () => {
+    const sidebarSlice: SidebarItem[] = [
+      {
+        type: 'category',
+        label: 'Category',
+        link: {
+          type: 'generated-index',
+          permalink: 'generated/permalink',
+        },
+        items: [],
+      },
+      {
+        type: 'category',
+        label: 'Category 2',
+        link: {
+          type: 'doc',
+          id: 'doc ID',
+        },
+        items: [],
+      },
+    ];
+
+    const processedSidebar = await testProcessSidebars(
+      {sidebar: sidebarSlice},
+      {},
+    );
+
+    expect(processedSidebar).toEqual({
+      sidebar: [
+        {
+          type: 'link',
+          label: 'Category',
+          href: 'generated/permalink',
+        },
+        {
+          type: 'doc',
+          label: 'Category 2',
+          id: 'doc ID',
+        },
+      ],
+    } as Sidebars);
+
+    await expect(async () => {
+      await testProcessSidebars({
+        sidebar: [
+          {
+            type: 'category',
+            label: 'Bad category',
+            items: [],
+          },
+        ],
+      });
+    }).rejects.toThrowErrorMatchingInlineSnapshot(
+      `"Sidebar category Bad category has neither any subitem nor a link. This makes this item not able to link to anything."`,
+    );
+  });
 });

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

@@ -117,6 +117,34 @@ async function processSidebar(
     item: NormalizedSidebarItem,
   ): Promise<SidebarItem[]> {
     if (item.type === 'category') {
+      // If the current category doesn't have subitems, we render a normal doc link instead.
+      if (item.items.length === 0) {
+        if (!item.link) {
+          throw new Error(
+            `Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`,
+          );
+        }
+        switch (item.link.type) {
+          case 'doc':
+            return [
+              {
+                type: 'doc',
+                label: item.label,
+                id: item.link.id,
+              },
+            ];
+          case 'generated-index':
+            return [
+              {
+                type: 'link',
+                label: item.label,
+                href: item.link.permalink,
+              },
+            ];
+          default:
+            throw new Error('Unexpected sidebar category link type');
+        }
+      }
       return [await processCategoryItem(item)];
     }
     if (item.type === 'autogenerated') {

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

@@ -39,9 +39,6 @@ export default function DocSidebarItem({
 }: Props): JSX.Element | null {
   switch (item.type) {
     case 'category':
-      if (item.items.length === 0) {
-        return null;
-      }
       return <DocSidebarItemCategory item={item} {...props} />;
     case 'link':
     default:

website/_dogfooding/_docs tests/tests/category-links/no-subdoc/index.md

@@ -0,0 +1,3 @@
+# No sub-docs
+
+The only doc of this category is the index page. It should show up as a regular doc link.

website/_dogfooding/docs-tests-sidebars.js

@@ -82,7 +82,13 @@ function generateHugeSidebarItems() {
 
   function generateRecursive(maxLevel, currentLevel = 0) {
     if (currentLevel === maxLevel) {
-      return [];
+      return [
+        {
+          type: 'link',
+          href: '/',
+          label: `Link (level ${currentLevel + 1})`,
+        },
+      ];
     }
 
     const linkItems = [...Array(linksCount).keys()].map((index) => ({

website/docs/guides/docs/sidebar/autogenerated.md

@@ -194,6 +194,19 @@ Naming your introductory document `README.md` makes it show up when browsing the
 
 :::
 
+:::tip
+
+If a folder only has one index page, it will be turned into a link instead of a category. This is useful for **asset collocation**:
+
+```
+some-doc
+├── index.md
+├── img1.png
+└── img2.png
+```
+
+:::
+
 <details>
 
 <summary>Customizing category index matching</summary>