@docusaurus/plugin-content-docs 0.0.0-4489 → 0.0.0-4493

package/lib/docs.d.ts

@@ -7,7 +7,7 @@
 import type { LoadContext } from '@docusaurus/types';
 import type { DocFile, DocMetadataBase, VersionMetadata, LoadedVersion } from './types';
 import type { SidebarsUtils } from './sidebars/utils';
-import type { MetadataOptions, PluginOptions } from '@docusaurus/plugin-content-docs';
+import type { MetadataOptions, PluginOptions, CategoryIndexMatcher, CategoryIndexMatcherParam } from '@docusaurus/plugin-content-docs';
 declare type LastUpdateOptions = Pick<PluginOptions, 'showLastUpdateAuthor' | 'showLastUpdateTime'>;
 export declare function readDocFile(versionMetadata: Pick<VersionMetadata, 'contentPath' | 'contentPathLocalized'>, source: string, options: LastUpdateOptions): Promise<DocFile>;
 export declare function readVersionDocs(versionMetadata: VersionMetadata, options: Pick<PluginOptions, 'include' | 'exclude' | 'showLastUpdateAuthor' | 'showLastUpdateTime'>): Promise<DocFile[]>;
@@ -29,10 +29,22 @@ export declare function getMainDocId({ docs, sidebarsUtils, }: {
     docs: DocMetadataBase[];
     sidebarsUtils: SidebarsUtils;
 }): string;
-export declare function isConventionalDocIndex(doc: {
-    source: DocMetadataBase['slug'];
-    sourceDirName: DocMetadataBase['sourceDirName'];
-}): boolean;
+export declare const isCategoryIndex: CategoryIndexMatcher;
+export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
+/**
+ * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ */
+export declare 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;
+};
 export declare function getDocIds(doc: DocMetadataBase): [string, string];
 export declare function createDocsByIdIndex<Doc extends {
     id: string;

package/lib/docs.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createDocsByIdIndex = exports.getDocIds = exports.isConventionalDocIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
+exports.createDocsByIdIndex = exports.getDocIds = exports.splitPath = exports.toCategoryIndexMatcherParam = exports.isCategoryIndex = exports.getMainDocId = exports.addDocNavigation = exports.processDocMetadata = exports.readVersionDocs = exports.readDocFile = void 0;
 const tslib_1 = require("tslib");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
@@ -232,26 +232,46 @@ function getMainDocId({ docs, sidebarsUtils, }) {
     return getMainDoc().unversionedId;
 }
 exports.getMainDocId = getMainDocId;
-function getLastPathSegment(str) {
-    return (0, lodash_1.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
-function isConventionalDocIndex(doc) {
-    // "@site/docs/folder/subFolder/subSubFolder/myDoc.md" => "myDoc"
-    const docName = path_1.default.parse(doc.source).name;
-    // "folder/subFolder/subSubFolder" => "subSubFolder"
-    const lastDirName = getLastPathSegment(doc.sourceDirName);
-    const eligibleDocIndexNames = ['index', 'readme', lastDirName.toLowerCase()];
-    return eligibleDocIndexNames.includes(docName.toLowerCase());
+const isCategoryIndex = ({ fileName, directories, }) => {
+    var _a;
+    const eligibleDocIndexNames = [
+        'index',
+        'readme',
+        (_a = directories[0]) === null || _a === void 0 ? void 0 : _a.toLowerCase(),
+    ];
+    return eligibleDocIndexNames.includes(fileName.toLowerCase());
+};
+exports.isCategoryIndex = isCategoryIndex;
+function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
+    // source + sourceDirName are always posix-style
+    return {
+        fileName: path_1.default.posix.parse(source).name,
+        extension: path_1.default.posix.parse(source).ext,
+        directories: sourceDirName.split(path_1.default.posix.sep).reverse(),
+    };
+}
+exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
+/**
+ * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ */
+function splitPath(str) {
+    return {
+        fileName: path_1.default.parse(str).name,
+        extension: path_1.default.parse(str).ext,
+        directories: path_1.default.dirname(str).split(path_1.default.sep).reverse(),
+    };
 }
-exports.isConventionalDocIndex = isConventionalDocIndex;
+exports.splitPath = splitPath;
 // Return both doc ids
 // TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
 // ("id" should be removed & "versionedId" should be renamed to "id")

package/lib/sidebars/generator.js

@@ -45,7 +45,7 @@ async function readCategoryMetadataFile(categoryDirPath) {
     return filePath ? tryReadFile(filePath) : null;
 }
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
     const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
     const findDoc = (docId) => docsById[docId];
     const getDoc = (docId) => {
@@ -133,7 +133,13 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs,
                 return allItems.find((item) => item.type === 'doc' && getLocalDocId(item.id) === localId);
             }
             function findConventionalCategoryDocLink() {
-                return allItems.find((item) => item.type === 'doc' && (0, docs_1.isConventionalDocIndex)(getDoc(item.id)));
+                return allItems.find((item) => {
+                    if (item.type !== 'doc') {
+                        return false;
+                    }
+                    const doc = getDoc(item.id);
+                    return isCategoryIndex((0, docs_1.toCategoryIndexMatcherParam)(doc));
+                });
             }
             function getCategoryLinkedDocId() {
                 var _a, _b;

package/lib/sidebars/processor.js

@@ -13,6 +13,7 @@ const generator_1 = require("./generator");
 const lodash_1 = require("lodash");
 const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
 const normalization_1 = require("./normalization");
+const docs_1 = require("../docs");
 function toSidebarItemsGeneratorDoc(doc) {
     return (0, lodash_1.pick)(doc, [
         'id',
@@ -46,6 +47,7 @@ async function processSidebar(unprocessedSidebar, params) {
             item,
             numberPrefixParser,
             defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+            isCategoryIndex: docs_1.isCategoryIndex,
             ...getSidebarItemsGeneratorDocsAndVersion(),
             options: sidebarOptions,
         });

package/lib/sidebars/types.d.ts

@@ -6,7 +6,7 @@
  */
 import type { Optional, Required } from 'utility-types';
 import type { DocMetadataBase, VersionMetadata } from '../types';
-import type { NumberPrefixParser, SidebarOptions } from '@docusaurus/plugin-content-docs';
+import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher } from '@docusaurus/plugin-content-docs';
 declare type Expand<T extends Record<string, unknown>> = {
     [P in keyof T]: T[P];
 };
@@ -121,6 +121,7 @@ export declare type SidebarItemsGeneratorArgs = {
     version: SidebarItemsGeneratorVersion;
     docs: SidebarItemsGeneratorDoc[];
     numberPrefixParser: NumberPrefixParser;
+    isCategoryIndex: CategoryIndexMatcher;
     options: SidebarOptions;
 };
 export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<SidebarItem[]>;

package/lib/slug.d.ts

@@ -9,7 +9,7 @@ import type { NumberPrefixParser } from '@docusaurus/plugin-content-docs';
 export default function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
     baseID: string;
     frontMatterSlug?: string;
-    source: DocMetadataBase['slug'];
+    source: DocMetadataBase['source'];
     sourceDirName: DocMetadataBase['sourceDirName'];
     stripDirNumberPrefixes?: boolean;
     numberPrefixParser?: NumberPrefixParser;

package/lib/slug.js

@@ -25,7 +25,8 @@ function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumbe
         }
         else {
             const dirNameSlug = getDirNameSlug();
-            if (!frontMatterSlug && (0, docs_1.isConventionalDocIndex)({ source, sourceDirName })) {
+            if (!frontMatterSlug &&
+                (0, docs_1.isCategoryIndex)((0, docs_1.toCategoryIndexMatcherParam)({ source, sourceDirName }))) {
                 return dirNameSlug;
             }
             const baseSlug = frontMatterSlug || baseID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4489",
+  "version": "0.0.0-4493",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -22,11 +22,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4489",
-    "@docusaurus/logger": "0.0.0-4489",
-    "@docusaurus/mdx-loader": "0.0.0-4489",
-    "@docusaurus/utils": "0.0.0-4489",
-    "@docusaurus/utils-validation": "0.0.0-4489",
+    "@docusaurus/core": "0.0.0-4493",
+    "@docusaurus/logger": "0.0.0-4493",
+    "@docusaurus/mdx-loader": "0.0.0-4493",
+    "@docusaurus/utils": "0.0.0-4493",
+    "@docusaurus/utils-validation": "0.0.0-4493",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.0",
     "import-fresh": "^3.2.2",
@@ -39,8 +39,8 @@
     "webpack": "^5.61.0"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4489",
-    "@docusaurus/types": "0.0.0-4489",
+    "@docusaurus/module-type-aliases": "0.0.0-4493",
+    "@docusaurus/types": "0.0.0-4493",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -55,5 +55,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "f4020aaf26717ce5e5085a949cf3b7e088bc386f"
+  "gitHead": "69f72486f48ed685cde2ab0e7764a96c3104bba6"
 }

package/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

package/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;

package/src/sidebars/generator.ts

@@ -25,7 +25,7 @@ import path from 'path';
 import fs from 'fs-extra';
 import Yaml from 'js-yaml';
 import {validateCategoryMetadataFile} from './validation';
-import {createDocsByIdIndex, isConventionalDocIndex} from '../docs';
+import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
 
 const BreadcrumbSeparator = '/';
 // To avoid possible name clashes with a folder of the same name as the ID
@@ -94,6 +94,7 @@ async function readCategoryMetadataFile(
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
 export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   numberPrefixParser,
+  isCategoryIndex,
   docs: allDocs,
   options,
   item: {dirName: autogenDir},
@@ -210,10 +211,13 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       }
 
       function findConventionalCategoryDocLink(): SidebarItemDoc | undefined {
-        return allItems.find(
-          (item) =>
-            item.type === 'doc' && isConventionalDocIndex(getDoc(item.id)),
-        ) as SidebarItemDoc | undefined;
+        return allItems.find((item) => {
+          if (item.type !== 'doc') {
+            return false;
+          }
+          const doc = getDoc(item.id);
+          return isCategoryIndex(toCategoryIndexMatcherParam(doc));
+        }) as SidebarItemDoc | undefined;
       }
 
       function getCategoryLinkedDocId(): string | undefined {

package/src/sidebars/processor.ts

@@ -25,6 +25,7 @@ import {DefaultSidebarItemsGenerator} from './generator';
 import {mapValues, memoize, pick} from 'lodash';
 import combinePromises from 'combine-promises';
 import {normalizeItem} from './normalization';
+import {isCategoryIndex} from '../docs';
 import type {Slugger} from '@docusaurus/utils';
 import type {
   NumberPrefixParser,
@@ -95,6 +96,7 @@ async function processSidebar(
       item,
       numberPrefixParser,
       defaultSidebarItemsGenerator: DefaultSidebarItemsGenerator,
+      isCategoryIndex,
       ...getSidebarItemsGeneratorDocsAndVersion(),
       options: sidebarOptions,
     });

package/src/sidebars/types.ts

@@ -10,6 +10,7 @@ import type {DocMetadataBase, VersionMetadata} from '../types';
 import type {
   NumberPrefixParser,
   SidebarOptions,
+  CategoryIndexMatcher,
 } from '@docusaurus/plugin-content-docs';
 
 // Makes all properties visible when hovering over the type
@@ -195,6 +196,7 @@ export type SidebarItemsGeneratorArgs = {
   version: SidebarItemsGeneratorVersion;
   docs: SidebarItemsGeneratorDoc[];
   numberPrefixParser: NumberPrefixParser;
+  isCategoryIndex: CategoryIndexMatcher;
   options: SidebarOptions;
 };
 export type SidebarItemsGenerator = (

package/src/slug.ts

@@ -16,7 +16,7 @@ import {
   stripPathNumberPrefixes,
 } from './numberPrefix';
 import type {DocMetadataBase} from './types';
-import {isConventionalDocIndex} from './docs';
+import {isCategoryIndex, toCategoryIndexMatcherParam} from './docs';
 import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 export default function getSlug({
@@ -29,7 +29,7 @@ export default function getSlug({
 }: {
   baseID: string;
   frontMatterSlug?: string;
-  source: DocMetadataBase['slug'];
+  source: DocMetadataBase['source'];
   sourceDirName: DocMetadataBase['sourceDirName'];
   stripDirNumberPrefixes?: boolean;
   numberPrefixParser?: NumberPrefixParser;
@@ -50,7 +50,10 @@ export default function getSlug({
       return frontMatterSlug;
     } else {
       const dirNameSlug = getDirNameSlug();
-      if (!frontMatterSlug && isConventionalDocIndex({source, sourceDirName})) {
+      if (
+        !frontMatterSlug &&
+        isCategoryIndex(toCategoryIndexMatcherParam({source, sourceDirName}))
+      ) {
         return dirNameSlug;
       }
       const baseSlug = frontMatterSlug || baseID;

package/src/types.ts

@@ -82,8 +82,8 @@ export type DocMetadataBase = LastUpdateData & {
   version: string;
   title: string;
   description: string;
-  source: string; // @site aliased source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
-  sourceDirName: string; // relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
+  source: string; // @site aliased posix source => "@site/docs/folder/subFolder/subSubFolder/myDoc.md"
+  sourceDirName: string; // posix path relative to the versioned docs folder (can be ".") => "folder/subFolder/subSubFolder"
   slug: string;
   permalink: string;
   sidebarPosition?: number;