feat(content-docs): expose isCategoryIndex matcher to customize conventions (#6451)

Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>

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

@@ -194,6 +194,102 @@ Naming your introductory document `README.md` makes it show up when browsing the
 
 :::
 
+<details>
+
+<summary>Customizing category index matching</summary>
+
+It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index.
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        async sidebarItemsGenerator({
+          ...args,
+          isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
+          defaultSidebarItemsGenerator,
+        }) {
+          return defaultSidebarItemsGenerator({
+            ...args,
+            // highlight-start
+            isCategoryIndex(doc) {
+              return (
+                // Also pick intro.md in addition to the default ones
+                doc.fileName.toLowerCase() === 'intro' ||
+                defaultCategoryIndexMatcher(doc)
+              );
+            },
+            // highlight-end
+          });
+        },
+      },
+    ],
+  ],
+};
+```
+
+Or choose to not have any category index convention.
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-content-docs',
+      {
+        async sidebarItemsGenerator({
+          ...args,
+          isCategoryIndex: defaultCategoryIndexMatcher, // The default matcher implementation, given below
+          defaultSidebarItemsGenerator,
+        }) {
+          return defaultSidebarItemsGenerator({
+            ...args,
+            // highlight-start
+            isCategoryIndex() {
+              // No doc will be automatically picked as category index
+              return false;
+            },
+            // highlight-end
+          });
+        },
+      },
+    ],
+  ],
+};
+```
+
+The `isCategoryIndex` matcher will be provided with three fields:
+
+- `fileName`, the file's name without extension and with casing preserved
+- `directories`, the list of directory names _from the lowest level to the highest level_, relative to the docs root directory
+- `extension`, the file's extension, with a leading dot.
+
+For example, for a doc file at `guides/sidebar/autogenerated.md`, the props the matcher receives are
+
+```js
+const props = {
+  fileName: 'autogenerated',
+  directories: ['sidebar', 'guides'],
+  extension: '.md',
+};
+```
+
+The default implementation is:
+
+```js
+function isCategoryIndex({fileName, directories}) {
+  const eligibleDocIndexNames = [
+    'index',
+    'readme',
+    directories[0].toLowerCase(),
+  ];
+  return eligibleDocIndexNames.includes(fileName.toLowerCase());
+}
+```
+
+</details>
+
 ## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
 
 For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
@@ -317,6 +413,7 @@ module.exports = {
           item,
           version,
           docs,
+          isCategoryIndex,
         }) {
           // Example: return an hardcoded list of static sidebar items
           return [