fix(content-docs): restore functionality when a category only has ind…

…ex page (#7385)

* fix(content-docs): restore functionality when a category only has index page

* use this internally

packages/docusaurus-plugin-content-docs/src/sidebars/README.md

@@ -6,4 +6,5 @@ This part is very complicated and hard to navigate. Sidebars are loaded through
 2. **Normalization**. The shorthands are expanded. This step is very lenient about the sidebars' shapes. Returns `NormalizedSidebars`.
 3. **Validation**. The normalized sidebars are validated. This step happens after normalization, because the normalized sidebars are easier to validate, and allows us to repeatedly validate & generate in the future.
 4. **Generation**. This step is done through the "processor" (naming is hard). The `autogenerated` items are unwrapped. In the future, steps 3 and 4 may be repeatedly done until all autogenerated items are unwrapped. Returns `ProcessedSidebars`.
+   - **Important**: this step should only care about unwrapping autogenerated items, not filtering them, writing additional metadata, applying defaults, etc.—everything will be handled in the post-processor. Important because the generator is exposed to the end-user and we want it to be easy to be reasoned about.
 5. **Post-processing**. Defaults are applied (collapsed states), category links are resolved, empty categories are flattened. Returns `Sidebars`.

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/index.test.ts.snap

@@ -1,5 +1,56 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
+exports[`loadSidebars loads sidebars with index-only categories 1`] = `
+{
+  "docs": [
+    {
+      "collapsed": true,
+      "collapsible": true,
+      "items": [
+        {
+          "id": "tutorials/tutorial-basics",
+          "label": "tutorial-basics",
+          "type": "doc",
+        },
+      ],
+      "label": "Tutorials",
+      "link": undefined,
+      "type": "category",
+    },
+    {
+      "id": "tutorials/tutorial-basics",
+      "label": "index-only",
+      "type": "doc",
+    },
+  ],
+}
+`;
+
+exports[`loadSidebars loads sidebars with interspersed draft items 1`] = `
+{
+  "sidebar": [
+    {
+      "id": "not-draft",
+      "label": "index not draft",
+      "type": "doc",
+    },
+    {
+      "collapsed": true,
+      "collapsible": true,
+      "items": [
+        {
+          "id": "not-draft",
+          "type": "doc",
+        },
+      ],
+      "label": "subitem not draft",
+      "link": undefined,
+      "type": "category",
+    },
+  ],
+}
+`;
+
 exports[`loadSidebars sidebars link 1`] = `
 {
   "docs": [

packages/docusaurus-plugin-content-docs/src/sidebars/__tests__/__snapshots__/postProcessor.test.ts.snap

@@ -60,14 +60,21 @@ exports[`postProcess corrects collapsed state inconsistencies 3`] = `
 }
 `;
 
-exports[`postProcess transforms category without subitems 1`] = `
+exports[`postProcess filters draft items 1`] = `
 {
   "sidebar": [
     {
-      "href": "version/generated/permalink",
+      "id": "another",
       "label": "Category",
-      "type": "link",
+      "type": "doc",
     },
+  ],
+}
+`;
+
+exports[`postProcess transforms category without subitems 1`] = `
+{
+  "sidebar": [
     {
       "id": "doc ID",
       "label": "Category 2",

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

@@ -7,6 +7,7 @@
 
 import {jest} from '@jest/globals';
 import path from 'path';
+import {createSlugger} from '@docusaurus/utils';
 import {loadSidebars, DisabledSidebars} from '../index';
 import type {SidebarProcessorParams} from '../types';
 import {DefaultSidebarItemsGenerator} from '../generator';
@@ -27,6 +28,7 @@ describe('loadSidebars', () => {
     ],
     drafts: [],
     version: {
+      path: 'version',
       contentPath: path.join(fixtureDir, 'docs'),
       contentPathLocalized: path.join(fixtureDir, 'docs'),
     },
@@ -124,6 +126,32 @@ describe('loadSidebars', () => {
     expect(result).toMatchSnapshot();
   });
 
+  it('loads sidebars with index-only categories', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-category-index.json');
+    const result = await loadSidebars(sidebarPath, {
+      ...params,
+      docs: [
+        {
+          id: 'tutorials/tutorial-basics',
+          source: '@site/docs/tutorials/tutorial-basics/index.md',
+          sourceDirName: 'tutorials/tutorial-basics',
+          frontMatter: {},
+        },
+      ],
+    });
+    expect(result).toMatchSnapshot();
+  });
+
+  it('loads sidebars with interspersed draft items', async () => {
+    const sidebarPath = path.join(fixtureDir, 'sidebars-drafts.json');
+    const result = await loadSidebars(sidebarPath, {
+      ...params,
+      drafts: [{id: 'draft1'}, {id: 'draft2'}, {id: 'draft3'}],
+      categoryLabelSlugger: createSlugger(),
+    });
+    expect(result).toMatchSnapshot();
+  });
+
   it('duplicate category metadata files', async () => {
     const sidebarPath = path.join(
       fixtureDir,

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

@@ -35,6 +35,7 @@ describe('postProcess', () => {
       {
         sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
         version: {path: 'version'},
+        drafts: [],
       },
     );
 
@@ -54,6 +55,7 @@ describe('postProcess', () => {
         {
           sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
           version: {path: 'version'},
+          drafts: [],
         },
       );
     }).toThrowErrorMatchingInlineSnapshot(
@@ -79,6 +81,7 @@ describe('postProcess', () => {
         {
           sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
           version: {path: 'version'},
+          drafts: [],
         },
       ),
     ).toMatchSnapshot();
@@ -99,6 +102,7 @@ describe('postProcess', () => {
         {
           sidebarOptions: {sidebarCollapsed: false, sidebarCollapsible: false},
           version: {path: 'version'},
+          drafts: [],
         },
       ),
     ).toMatchSnapshot();
@@ -118,6 +122,37 @@ describe('postProcess', () => {
         {
           sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: false},
           version: {path: 'version'},
+          drafts: [],
+        },
+      ),
+    ).toMatchSnapshot();
+  });
+
+  it('filters draft items', () => {
+    expect(
+      postProcessSidebars(
+        {
+          sidebar: [
+            {
+              type: 'category',
+              label: 'Category',
+              items: [{type: 'doc', id: 'foo'}],
+            },
+            {
+              type: 'category',
+              label: 'Category',
+              link: {
+                type: 'doc',
+                id: 'another',
+              },
+              items: [{type: 'doc', id: 'foo'}],
+            },
+          ],
+        },
+        {
+          sidebarOptions: {sidebarCollapsed: true, sidebarCollapsible: true},
+          version: {path: 'version'},
+          drafts: [{id: 'foo', unversionedId: 'foo'}],
         },
       ),
     ).toMatchSnapshot();