@docusaurus/plugin-content-docs 0.0.0-4660 → 0.0.0-4665

package/lib/sidebars/generator.js

@@ -14,8 +14,6 @@ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const path_1 = tslib_1.__importDefault(require("path"));
 const docs_1 = require("../docs");
 const BreadcrumbSeparator = '/';
-// To avoid possible name clashes with a folder of the same name as the ID
-const docIdPrefix = '$doc$/';
 // Just an alias to the make code more explicit
 function getLocalDocId(docId) {
     return lodash_1.default.last(docId.split('/'));
@@ -72,14 +70,16 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
         const treeRoot = {};
         docs.forEach((doc) => {
             const breadcrumb = getRelativeBreadcrumb(doc);
-            let currentDir = treeRoot; // We walk down the file's path to generate the fs structure
+            // We walk down the file's path to generate the fs structure
+            let currentDir = treeRoot;
             breadcrumb.forEach((dir) => {
                 if (typeof currentDir[dir] === 'undefined') {
                     currentDir[dir] = {}; // Create new folder.
                 }
                 currentDir = currentDir[dir]; // Go into the subdirectory.
             });
-            currentDir[`${docIdPrefix}${doc.id}`] = null; // We've walked through the file path. Register the file in this directory.
+            // We've walked through the path. Register the file in this directory.
+            currentDir[path_1.default.basename(doc.source)] = doc.id;
         });
         return treeRoot;
     }
@@ -88,23 +88,24 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
      * (From a record to an array of items, akin to normalizing shorthand)
      */
     function generateSidebar(fsModel) {
-        function createDocItem(id) {
+        function createDocItem(id, fullPath, fileName) {
             const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = getDoc(id);
             return {
                 type: 'doc',
                 id,
                 position,
+                source: fileName,
                 // We don't want these fields to magically appear in the generated
                 // sidebar
                 ...(label !== undefined && { label }),
                 ...(className !== undefined && { className }),
             };
         }
-        async function createCategoryItem(dir, fullPath, folderName) {
+        function createCategoryItem(dir, fullPath, folderName) {
             const categoryMetadata = categoriesMetadata[(0, utils_1.posixPath)(path_1.default.join(autogenDir, fullPath))];
             const className = categoryMetadata?.className;
             const { filename, numberPrefix } = numberPrefixParser(folderName);
-            const allItems = await Promise.all(Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`)));
+            const allItems = Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`));
             // Try to match a doc inside the category folder,
             // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
             function findDocByLocalId(localId) {
@@ -147,19 +148,20 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
                 collapsible: categoryMetadata?.collapsible,
                 collapsed: categoryMetadata?.collapsed,
                 position: categoryMetadata?.position ?? numberPrefix,
+                source: folderName,
                 ...(className !== undefined && { className }),
                 items,
                 ...(link && { link }),
             };
         }
-        async function dirToItem(dir, // The directory item to be transformed.
-        itemKey, // For docs, it's the doc ID; for categories, it's used to generate the next `relativePath`.
+        function dirToItem(dir, // The directory item to be transformed.
+        itemKey, // File/folder name; for categories, it's used to generate the next `relativePath`.
         fullPath) {
-            return dir
+            return typeof dir === 'object'
                 ? createCategoryItem(dir, fullPath, itemKey)
-                : createDocItem(itemKey.substring(docIdPrefix.length));
+                : createDocItem(dir, fullPath, itemKey);
         }
-        return Promise.all(Object.entries(fsModel).map(([key, content]) => dirToItem(content, key, key)));
+        return Object.entries(fsModel).map(([key, content]) => dirToItem(content, key, key));
     }
     /**
      * Step 4. Recursively sort the categories/docs + remove the "position"
@@ -175,13 +177,16 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
             }
             return item;
         });
-        const sortedSidebarItems = lodash_1.default.sortBy(processedSidebarItems, (item) => item.position);
-        return sortedSidebarItems.map(({ position, ...item }) => item);
+        const sortedSidebarItems = lodash_1.default.sortBy(processedSidebarItems, [
+            'position',
+            'source',
+        ]);
+        return sortedSidebarItems.map(({ position, source, ...item }) => item);
     }
     // TODO: the whole code is designed for pipeline operator
     const docs = getAutogenDocs();
     const fsModel = treeify(docs);
-    const sidebarWithPosition = await generateSidebar(fsModel);
+    const sidebarWithPosition = generateSidebar(fsModel);
     const sortedSidebar = sortItems(sidebarWithPosition);
     return sortedSidebar;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4660",
+  "version": "0.0.0-4665",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -23,11 +23,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4660",
-    "@docusaurus/logger": "0.0.0-4660",
-    "@docusaurus/mdx-loader": "0.0.0-4660",
-    "@docusaurus/utils": "0.0.0-4660",
-    "@docusaurus/utils-validation": "0.0.0-4660",
+    "@docusaurus/core": "0.0.0-4665",
+    "@docusaurus/logger": "0.0.0-4665",
+    "@docusaurus/mdx-loader": "0.0.0-4665",
+    "@docusaurus/utils": "0.0.0-4665",
+    "@docusaurus/utils-validation": "0.0.0-4665",
     "combine-promises": "^1.1.0",
     "fs-extra": "^10.0.1",
     "import-fresh": "^3.3.0",
@@ -39,8 +39,8 @@
     "webpack": "^5.69.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "0.0.0-4660",
-    "@docusaurus/types": "0.0.0-4660",
+    "@docusaurus/module-type-aliases": "0.0.0-4665",
+    "@docusaurus/types": "0.0.0-4665",
     "@types/js-yaml": "^4.0.5",
     "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
@@ -56,5 +56,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "78417b2a5827489b7e0d8b255843800151615a7b"
+  "gitHead": "88df79f3adcef89d18f58736a8293bfdb011d2d3"
 }

package/src/sidebars/generator.ts

@@ -20,8 +20,6 @@ import path from 'path';
 import {createDocsByIdIndex, toCategoryIndexMatcherParam} from '../docs';
 
 const BreadcrumbSeparator = '/';
-// To avoid possible name clashes with a folder of the same name as the ID
-const docIdPrefix = '$doc$/';
 
 // Just an alias to the make code more explicit
 function getLocalDocId(docId: string): string {
@@ -31,16 +29,20 @@ function getLocalDocId(docId: string): string {
 export const CategoryMetadataFilenameBase = '_category_';
 export const CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
 
-type WithPosition<T> = T & {position?: number};
+type WithPosition<T> = T & {
+  position?: number;
+  /** The source is the file/folder name */
+  source?: string;
+};
 
 /**
  * A representation of the fs structure. For each object entry:
  * If it's a folder, the key is the directory name, and value is the directory
- * content; If it's a doc file, the key is the doc id prefixed with '$doc$/',
- * and value is null
+ * content; If it's a doc file, the key is the doc's source file name, and value
+ * is the doc ID
  */
 type Dir = {
-  [item: string]: Dir | null;
+  [item: string]: Dir | string;
 };
 
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
@@ -108,14 +110,16 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
     const treeRoot: Dir = {};
     docs.forEach((doc) => {
       const breadcrumb = getRelativeBreadcrumb(doc);
-      let currentDir = treeRoot; // We walk down the file's path to generate the fs structure
+      // We walk down the file's path to generate the fs structure
+      let currentDir = treeRoot;
       breadcrumb.forEach((dir) => {
         if (typeof currentDir[dir] === 'undefined') {
           currentDir[dir] = {}; // Create new folder.
         }
-        currentDir = currentDir[dir]!; // Go into the subdirectory.
+        currentDir = currentDir[dir] as Dir; // Go into the subdirectory.
       });
-      currentDir[`${docIdPrefix}${doc.id}`] = null; // We've walked through the file path. Register the file in this directory.
+      // We've walked through the path. Register the file in this directory.
+      currentDir[path.basename(doc.source)] = doc.id;
     });
     return treeRoot;
   }
@@ -126,8 +130,12 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
    */
   function generateSidebar(
     fsModel: Dir,
-  ): Promise<WithPosition<NormalizedSidebarItem>[]> {
-    function createDocItem(id: string): WithPosition<SidebarItemDoc> {
+  ): WithPosition<NormalizedSidebarItem>[] {
+    function createDocItem(
+      id: string,
+      fullPath: string,
+      fileName: string,
+    ): WithPosition<SidebarItemDoc> {
       const {
         sidebarPosition: position,
         frontMatter: {sidebar_label: label, sidebar_class_name: className},
@@ -136,25 +144,24 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         type: 'doc',
         id,
         position,
+        source: fileName,
         // We don't want these fields to magically appear in the generated
         // sidebar
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
       };
     }
-    async function createCategoryItem(
+    function createCategoryItem(
       dir: Dir,
       fullPath: string,
       folderName: string,
-    ): Promise<WithPosition<NormalizedSidebarItemCategory>> {
+    ): WithPosition<NormalizedSidebarItemCategory> {
       const categoryMetadata =
         categoriesMetadata[posixPath(path.join(autogenDir, fullPath))];
       const className = categoryMetadata?.className;
       const {filename, numberPrefix} = numberPrefixParser(folderName);
-      const allItems = await Promise.all(
-        Object.entries(dir).map(([key, content]) =>
-          dirToItem(content, key, `${fullPath}/${key}`),
-        ),
+      const allItems = Object.entries(dir).map(([key, content]) =>
+        dirToItem(content, key, `${fullPath}/${key}`),
       );
 
       // Try to match a doc inside the category folder,
@@ -211,24 +218,23 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         collapsible: categoryMetadata?.collapsible,
         collapsed: categoryMetadata?.collapsed,
         position: categoryMetadata?.position ?? numberPrefix,
+        source: folderName,
         ...(className !== undefined && {className}),
         items,
         ...(link && {link}),
       };
     }
-    async function dirToItem(
-      dir: Dir | null, // The directory item to be transformed.
-      itemKey: string, // For docs, it's the doc ID; for categories, it's used to generate the next `relativePath`.
+    function dirToItem(
+      dir: Dir | string, // The directory item to be transformed.
+      itemKey: string, // File/folder name; for categories, it's used to generate the next `relativePath`.
       fullPath: string, // `dir`'s full path relative to the autogen dir.
-    ): Promise<WithPosition<NormalizedSidebarItem>> {
-      return dir
+    ): WithPosition<NormalizedSidebarItem> {
+      return typeof dir === 'object'
         ? createCategoryItem(dir, fullPath, itemKey)
-        : createDocItem(itemKey.substring(docIdPrefix.length));
+        : createDocItem(dir, fullPath, itemKey);
     }
-    return Promise.all(
-      Object.entries(fsModel).map(([key, content]) =>
-        dirToItem(content, key, key),
-      ),
+    return Object.entries(fsModel).map(([key, content]) =>
+      dirToItem(content, key, key),
     );
   }
 
@@ -248,16 +254,16 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
       }
       return item;
     });
-    const sortedSidebarItems = _.sortBy(
-      processedSidebarItems,
-      (item) => item.position,
-    );
-    return sortedSidebarItems.map(({position, ...item}) => item);
+    const sortedSidebarItems = _.sortBy(processedSidebarItems, [
+      'position',
+      'source',
+    ]);
+    return sortedSidebarItems.map(({position, source, ...item}) => item);
   }
   // TODO: the whole code is designed for pipeline operator
   const docs = getAutogenDocs();
   const fsModel = treeify(docs);
-  const sidebarWithPosition = await generateSidebar(fsModel);
+  const sidebarWithPosition = generateSidebar(fsModel);
   const sortedSidebar = sortItems(sidebarWithPosition);
   return sortedSidebar;
 };