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

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

website/docs/api/plugins/plugin-content-docs.md

@@ -77,6 +77,12 @@ type PrefixParser = (filename: string) => {
   numberPrefix?: number;
 };
 
+type CategoryIndexMatcher = (doc: {
+  fileName: string;
+  directories: string[];
+  extension: string;
+}) => boolean;
+
 type SidebarGenerator = (generatorArgs: {
   item: {type: 'autogenerated'; dirName: string}; // the sidebar item with type "autogenerated"
   version: {contentPath: string; versionName: string}; // the current version
@@ -88,6 +94,7 @@ type SidebarGenerator = (generatorArgs: {
     sidebarPosition?: number | undefined;
   }>; // all the docs of that version (unfiltered)
   numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
+  isCategoryIndex: CategoryIndexMatcher; // the default category index matcher, that you can override
   defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus
 }) => Promise<SidebarItem[]>;
 
@@ -141,6 +148,7 @@ const config = {
     item,
     version,
     docs,
+    isCategoryIndex,
   }) {
     // Use the provided data to generate a custom sidebar slice
     return [
@@ -274,15 +282,15 @@ website/i18n/[locale]/docusaurus-plugin-content-docs
 │
 │ # translations for website/docs
 ├── current
-│   ├── api
-│   │   └── config.md
-│   └── getting-started.md
+│   ├── api
+│   │   └── config.md
+│   └── getting-started.md
 ├── current.json
 │
 │ # translations for website/versioned_docs/version-1.0.0
 ├── version-1.0.0
-│   ├── api
-│   │   └── config.md
-│   └── getting-started.md
+│   ├── api
+│   │   └── config.md
+│   └── getting-started.md
 └── version-1.0.0.json
 ```

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 [