feat(content-docs): allow explicitly disabling index page for generated category (#6452)

* feat(content-docs): allow explicitly disabling index page for generated category

* docs

* add test

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

@@ -416,6 +416,10 @@ describe('DefaultSidebarItemsGenerator', () => {
           id: 'doc3', // Using a "local doc id" ("doc1" instead of "parent/doc1") on purpose
         },
       },
+      'Category2/_category_.yml': {
+        label: 'Category 2 label',
+        link: null,
+      },
     });
 
     const sidebarSlice = await DefaultSidebarItemsGenerator({
@@ -447,6 +451,24 @@ describe('DefaultSidebarItemsGenerator', () => {
           sourceDirName: 'Category',
           frontMatter: {},
         },
+        {
+          id: 'parent/doc4',
+          source: '@site/docs/Category2/doc1.md',
+          sourceDirName: 'Category2',
+          frontMatter: {},
+        },
+        {
+          id: 'parent/doc5',
+          source: '@site/docs/Category2/index.md',
+          sourceDirName: 'Category2',
+          frontMatter: {},
+        },
+        {
+          id: 'parent/doc6',
+          source: '@site/docs/Category2/doc3.md',
+          sourceDirName: 'Category2',
+          frontMatter: {},
+        },
       ],
       options: {
         sidebarCollapsed: true,
@@ -475,6 +497,26 @@ describe('DefaultSidebarItemsGenerator', () => {
           },
         ],
       },
+      {
+        type: 'category',
+        label: 'Category 2 label',
+        collapsed: true,
+        collapsible: true,
+        items: [
+          {
+            id: 'parent/doc4',
+            type: 'doc',
+          },
+          {
+            id: 'parent/doc5',
+            type: 'doc',
+          },
+          {
+            id: 'parent/doc6',
+            type: 'doc',
+          },
+        ],
+      },
     ] as Sidebar);
   });
 

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

@@ -45,7 +45,7 @@ export type CategoryMetadataFile = {
   collapsed?: boolean;
   collapsible?: boolean;
   className?: string;
-  link?: SidebarItemCategoryLinkConfig;
+  link?: SidebarItemCategoryLinkConfig | null;
 
   // TODO should we allow "items" here? how would this work? would an "autogenerated" type be allowed?
   // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
@@ -222,8 +222,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
 
       function getCategoryLinkedDocId(): string | undefined {
         const link = categoryMetadata?.link;
-        if (link) {
-          if (link.type === 'doc') {
+        if (link !== undefined) {
+          if (link && link.type === 'doc') {
             return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
           } else {
             // We don't continue for other link types on purpose!

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

@@ -56,6 +56,7 @@ const sidebarItemLinkSchema = sidebarItemBaseSchema.append<SidebarItemLink>({
 });
 
 const sidebarItemCategoryLinkSchema = Joi.object<SidebarItemCategoryLink>()
+  .allow(null)
   .when('.type', {
     switch: [
       {

website/_dogfooding/_docs tests/tests/category-links/no-index-doc/_category_.json

@@ -0,0 +1,3 @@
+{
+  "link": null
+}

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

@@ -0,0 +1,3 @@
+# Index
+
+This file (`index.md`) is supposed to be a category index, but it isn't because we have set `link: null` in the `_category_.json`.

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

@@ -0,0 +1,3 @@
+# Sample doc
+
+Lorem Ipsum

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

@@ -352,6 +352,8 @@ If the `link` is explicitly specified, Docusaurus will not apply any [default co
 
 The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist.
 
+You can also use `link: null` to opt out of default conventions and not generate any category index page.
+
 :::
 
 :::info