feat(content-docs): expose isCategoryIndex matcher to customize conve…

…ntions (#6451)

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

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

@@ -1491,6 +1491,7 @@ Object {
       "unversionedId": "installation",
     },
   ],
+  "isCategoryIndex": [Function],
   "item": Object {
     "dirName": ".",
     "type": "autogenerated",

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

@@ -12,7 +12,7 @@ import {
   readVersionDocs,
   readDocFile,
   addDocNavigation,
-  isConventionalDocIndex,
+  isCategoryIndex,
 } from '../docs';
 import {loadSidebars} from '../sidebars';
 import {readVersionsMetadata} from '../versions';
@@ -938,108 +938,124 @@ describe('versioned site', () => {
 describe('isConventionalDocIndex', () => {
   test('supports readme', () => {
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'readme.md',
+      isCategoryIndex({
+        fileName: 'readme',
+        directories: ['doesNotMatter'],
+        extension: '.md',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'readme.mdx',
+      isCategoryIndex({
+        fileName: 'readme',
+        directories: ['doesNotMatter'],
+        extension: '.mdx',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'README.md',
+      isCategoryIndex({
+        fileName: 'README',
+        directories: ['doesNotMatter'],
+        extension: '.md',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'parent/ReAdMe',
+      isCategoryIndex({
+        fileName: 'ReAdMe',
+        directories: ['doesNotMatter'],
+        extension: '',
       }),
     ).toEqual(true);
   });
 
   test('supports index', () => {
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'index.md',
+      isCategoryIndex({
+        fileName: 'index',
+        directories: ['doesNotMatter'],
+        extension: '.md',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'index.mdx',
+      isCategoryIndex({
+        fileName: 'index',
+        directories: ['doesNotMatter'],
+        extension: '.mdx',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'INDEX.md',
+      isCategoryIndex({
+        fileName: 'INDEX',
+        directories: ['doesNotMatter'],
+        extension: '.md',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'parent/InDeX',
+      isCategoryIndex({
+        fileName: 'InDeX',
+        directories: ['doesNotMatter'],
+        extension: '',
       }),
     ).toEqual(true);
   });
 
   test('supports <categoryName>/<categoryName>.md', () => {
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'someCategory',
-        source: 'someCategory',
+      isCategoryIndex({
+        fileName: 'someCategory',
+        directories: ['someCategory', 'doesNotMatter'],
+        extension: '',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'someCategory',
-        source: 'someCategory.md',
+      isCategoryIndex({
+        fileName: 'someCategory',
+        directories: ['someCategory'],
+        extension: '.md',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'someCategory',
-        source: 'someCategory.mdx',
+      isCategoryIndex({
+        fileName: 'someCategory',
+        directories: ['someCategory'],
+        extension: '.mdx',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'some_category',
-        source: 'SOME_CATEGORY.md',
+      isCategoryIndex({
+        fileName: 'SOME_CATEGORY',
+        directories: ['some_category'],
+        extension: '.md',
       }),
     ).toEqual(true);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'some_category',
-        source: 'parent/some_category',
+      isCategoryIndex({
+        fileName: 'some_category',
+        directories: ['some_category'],
+        extension: '',
       }),
     ).toEqual(true);
   });
 
   test('reject other cases', () => {
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'someCategory',
-        source: 'some_Category',
+      isCategoryIndex({
+        fileName: 'some_Category',
+        directories: ['someCategory'],
+        extension: '',
       }),
     ).toEqual(false);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'read_me',
+      isCategoryIndex({
+        fileName: 'read_me',
+        directories: ['doesNotMatter'],
+        extension: '',
       }),
     ).toEqual(false);
     expect(
-      isConventionalDocIndex({
-        sourceDirName: 'doesNotMatter',
-        source: 'the index',
+      isCategoryIndex({
+        fileName: 'the index',
+        directories: ['doesNotMatter'],
+        extension: '',
       }),
     ).toEqual(false);
   });

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

@@ -8,7 +8,7 @@
 import path from 'path';
 import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
-import {keyBy, last} from 'lodash';
+import {keyBy} from 'lodash';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -41,6 +41,8 @@ import {toDocNavigationLink, toNavigationLink} from './sidebars/utils';
 import type {
   MetadataOptions,
   PluginOptions,
+  CategoryIndexMatcher,
+  CategoryIndexMatcherParam,
 } from '@docusaurus/plugin-content-docs';
 
 type LastUpdateOptions = Pick<
@@ -367,31 +369,62 @@ export function getMainDocId({
   return getMainDoc().unversionedId;
 }
 
-function getLastPathSegment(str: string): string {
-  return last(str.split('/'))!;
-}
-
 // By convention, Docusaurus considers some docs are "indexes":
 // - index.md
 // - readme.md
 // - <folder>/<folder>.md
 //
+// This function is the default implementation of this convention
+//
 // Those index docs produce a different behavior
 // - Slugs do not end with a weird "/index" suffix
 // - Auto-generated sidebar categories link to them as intro
-export function isConventionalDocIndex(doc: {
-  source: DocMetadataBase['slug'];
-  sourceDirName: DocMetadataBase['sourceDirName'];
-}): boolean {
-  // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
-  const docName = path.parse(doc.source).name;
-
-  // "folder/subFolder/subSubFolder" => "subSubFolder"
-  const lastDirName = getLastPathSegment(doc.sourceDirName);
-
-  const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
+export const isCategoryIndex: CategoryIndexMatcher = ({
+  fileName,
+  directories,
+}): boolean => {
+  const eligibleDocIndexNames = [
+    'index',
+    'readme',
+    directories[0]?.toLowerCase(),
+  ];
+  return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+
+export function toCategoryIndexMatcherParam({
+  source,
+  sourceDirName,
+}: Pick<
+  DocMetadataBase,
+  'source' | 'sourceDirName'
+>): CategoryIndexMatcherParam {
+  // source + sourceDirName are always posix-style
+  return {
+    fileName: path.posix.parse(source).name,
+    extension: path.posix.parse(source).ext,
+    directories: sourceDirName.split(path.posix.sep).reverse(),
+  };
+}
 
-  return eligibleDocIndexNames.includes(docName.toLowerCase());
+/**
+ * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ */
+export function splitPath(str: string): {
+  /**
+   * The list of directories, from lowest level to highest.
+   * If there's no dir name, directories is ['.']
+   */
+  directories: string[];
+  /** The file name, without extension */
+  fileName: string;
+  /** The extension, with a leading dot */
+  extension: string;
+} {
+  return {
+    fileName: path.parse(str).name,
+    extension: path.parse(str).ext,
+    directories: path.dirname(str).split(path.sep).reverse(),
+  };
 }
 
 // Return both doc ids

packages/docusaurus-plugin-content-docs/src/plugin-content-docs.d.ts

@@ -13,6 +13,15 @@ declare module '@docusaurus/plugin-content-docs' {
     numberPrefix?: number;
   };
 
+  export type CategoryIndexMatcherParam = {
+    fileName: string;
+    directories: string[];
+    extension: string;
+  };
+  export type CategoryIndexMatcher = (
+    param: CategoryIndexMatcherParam,
+  ) => boolean;
+
   export type EditUrlFunction = (editUrlParams: {
     version: string;
     versionDocsDirPath: string;