@docusaurus/plugin-content-docs 0.0.0-4521 → 0.0.0-4526

package/lib/slug.js

@@ -23,15 +23,13 @@ function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumbe
         if (frontMatterSlug === null || frontMatterSlug === void 0 ? void 0 : frontMatterSlug.startsWith('/')) {
             return frontMatterSlug;
         }
-        else {
-            const dirNameSlug = getDirNameSlug();
-            if (!frontMatterSlug &&
-                (0, docs_1.isCategoryIndex)((0, docs_1.toCategoryIndexMatcherParam)({ source, sourceDirName }))) {
-                return dirNameSlug;
-            }
-            const baseSlug = frontMatterSlug || baseID;
-            return (0, utils_1.resolvePathname)(baseSlug, getDirNameSlug());
+        const dirNameSlug = getDirNameSlug();
+        if (!frontMatterSlug &&
+            (0, docs_1.isCategoryIndex)((0, docs_1.toCategoryIndexMatcherParam)({ source, sourceDirName }))) {
+            return dirNameSlug;
         }
+        const baseSlug = frontMatterSlug || baseID;
+        return (0, utils_1.resolvePathname)(baseSlug, getDirNameSlug());
     }
     function ensureValidSlug(slug) {
         if (!(0, utils_1.isValidPathname)(slug)) {

package/lib/translations.js

@@ -15,11 +15,9 @@ function getVersionFileName(versionName) {
     if (versionName === constants_1.CURRENT_VERSION_NAME) {
         return versionName;
     }
-    else {
-        // I don't like this "version-" prefix,
-        // but it's for consistency with site/versioned_docs
-        return `version-${versionName}`;
-    }
+    // I don't like this "version-" prefix,
+    // but it's for consistency with site/versioned_docs
+    return `version-${versionName}`;
 }
 // TODO legacy, the sidebar name is like "version-2.0.0-alpha.66/docs"
 // input: "version-2.0.0-alpha.66/docs"
@@ -44,7 +42,8 @@ function getDocTranslations(doc: DocMetadata): TranslationFileContent {
       ? {
           [`${doc.unversionedId}.sidebar_label`]: {
             message: doc.sidebar_label,
-            description: `The sidebar label for doc with id=${doc.unversionedId}`,
+            description:
+              `The sidebar label for doc with id=${doc.unversionedId}`,
           },
         }
       : undefined),
@@ -181,7 +180,8 @@ function getVersionTranslationFiles(version) {
         },
     };
     const sidebarsTranslations = getSidebarsTranslations(version);
-    // const docsTranslations: TranslationFileContent = getDocsTranslations(version);
+    // const docsTranslations: TranslationFileContent =
+    //   getDocsTranslations(version);
     return [
         {
             path: getVersionFileName(version.versionName),

package/lib/versions.js

@@ -16,12 +16,9 @@ const lodash_1 = require("lodash");
 const sidebars_1 = require("./sidebars");
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir, pluginId) {
-    if (pluginId === utils_1.DEFAULT_PLUGIN_ID) {
-        return fileOrDir;
-    }
-    else {
-        return `${pluginId}_${fileOrDir}`;
-    }
+    return pluginId === utils_1.DEFAULT_PLUGIN_ID
+        ? fileOrDir
+        : `${pluginId}_${fileOrDir}`;
 }
 function getVersionedDocsDirPath(siteDir, pluginId) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId));
@@ -57,9 +54,7 @@ async function readVersionsFile(siteDir, pluginId) {
         ensureValidVersionArray(content);
         return content;
     }
-    else {
-        return null;
-    }
+    return null;
 }
 async function readVersionNames(siteDir, options) {
     const versionFileContent = await readVersionsFile(siteDir, options.id);
@@ -149,13 +144,11 @@ function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }
         return null;
     }
     // Upcoming versions: unreleased banner
-    else if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
+    if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
         return 'unreleased';
     }
     // Older versions: display unmaintained banner
-    else {
-        return 'unmaintained';
-    }
+    return 'unmaintained';
 }
 function getVersionBanner({ versionName, versionNames, lastVersionName, options, }) {
     var _a;
@@ -245,8 +238,9 @@ function checkVersionMetadataPaths({ versionMetadata, context, }) {
     if (!fs_extra_1.default.existsSync(contentPath)) {
         throw new Error(`The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path_1.default.relative(siteDir, contentPath)}.`);
     }
-    // If the current version defines a path to a sidebar file  that does not exist, we throw!
-    // Note: for versioned sidebars, the file may not exist (as we prefer to not create it rather than to create an empty file)
+    // If the current version defines a path to a sidebar file that does not
+    // exist, we throw! Note: for versioned sidebars, the file may not exist (as
+    // we prefer to not create it rather than to create an empty file)
     // See https://github.com/facebook/docusaurus/issues/3366
     // See https://github.com/facebook/docusaurus/pull/4775
     if (isCurrentVersion &&
@@ -266,9 +260,7 @@ function getDefaultLastVersionName(versionNames) {
     if (versionNames.length === 1) {
         return versionNames[0];
     }
-    else {
-        return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
-    }
+    return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
 }
 function checkVersionsOptions(availableVersionNames, options) {
     const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
@@ -303,9 +295,7 @@ function filterVersions(versionNamesUnfiltered, options) {
     if (options.onlyIncludeVersions) {
         return versionNamesUnfiltered.filter((name) => (options.onlyIncludeVersions || []).includes(name));
     }
-    else {
-        return versionNamesUnfiltered;
-    }
+    return versionNamesUnfiltered;
 }
 async function readVersionsMetadata({ context, options, }) {
     var _a;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "0.0.0-4521",
+  "version": "0.0.0-4526",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
@@ -22,11 +22,11 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4521",
-    "@docusaurus/logger": "0.0.0-4521",
-    "@docusaurus/mdx-loader": "0.0.0-4521",
-    "@docusaurus/utils": "0.0.0-4521",
-    "@docusaurus/utils-validation": "0.0.0-4521",
+    "@docusaurus/core": "0.0.0-4526",
+    "@docusaurus/logger": "0.0.0-4526",
+    "@docusaurus/mdx-loader": "0.0.0-4526",
+    "@docusaurus/utils": "0.0.0-4526",
+    "@docusaurus/utils-validation": "0.0.0-4526",
     "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-4521",
-    "@docusaurus/types": "0.0.0-4521",
+    "@docusaurus/module-type-aliases": "0.0.0-4526",
+    "@docusaurus/types": "0.0.0-4526",
     "@types/js-yaml": "^4.0.0",
     "@types/picomatch": "^2.2.1",
     "commander": "^5.1.0",
@@ -56,5 +56,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "10eacaa44e87420d300c367fc5e1538c21485767"
+  "gitHead": "3086e9e823783e306698097d959007f44de275b1"
 }

package/src/cli.ts

@@ -20,7 +20,7 @@ import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
 
-function createVersionedSidebarFile({
+async function createVersionedSidebarFile({
   siteDir,
   pluginId,
   sidebarPath,
@@ -32,10 +32,12 @@ function createVersionedSidebarFile({
   version: string;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact older, versioned sidebars
-  const sidebars = loadSidebarsFile(sidebarPath);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let
+  // plugin option changes to impact older, versioned sidebars
+  const sidebars = await loadSidebarsFile(sidebarPath);
 
-  // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
+  // Do not create a useless versioned sidebars file if sidebars file is empty
+  // or sidebars are disabled/false)
   const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
@@ -54,12 +56,12 @@ function createVersionedSidebarFile({
 }
 
 // Tests depend on non-default export for mocking.
-export function cliDocsVersionCommand(
+export async function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
   options: PathOptions & SidebarOptions,
-): void {
+): Promise<void> {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
   const pluginIdLogPrefix =
@@ -125,7 +127,7 @@ export function cliDocsVersionCommand(
     throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
   }
 
-  createVersionedSidebarFile({
+  await createVersionedSidebarFile({
     siteDir,
     pluginId,
     version,

package/src/client/docsClientUtils.ts

@@ -28,7 +28,7 @@ export function getActivePlugin(
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
   const activeEntry = Object.entries(allPluginDatas)
-    // A quick route sorting: '/android/foo' should match '/android' instead of '/'
+    // Route sorting: '/android/foo' should match '/android' instead of '/'
     .sort((a, b) => b[1].path.localeCompare(a[1].path))
     .find(
       ([, pluginData]) =>
@@ -67,7 +67,7 @@ export const getActiveVersion = (
 ): GlobalVersion | undefined => {
   const lastVersion = getLatestVersion(data);
   // Last version is a route like /docs/*,
-  // we need to try to match it last or it would match /docs/version-1.0/* as well
+  // we need to match it last or it would match /docs/version-1.0/* as well
   const orderedVersionsMetadata = [
     ...data.versions.filter((version) => version !== lastVersion),
     lastVersion,

package/src/client/globalDataHooks.ts

@@ -27,12 +27,13 @@ import type {
   GetActivePluginOptions,
 } from '@docusaurus/plugin-content-docs/client';
 
-// Important to use a constant object to avoid React useEffect executions etc...,
+// Important to use a constant object to avoid React useEffect executions etc.
 // see https://github.com/facebook/docusaurus/issues/5089
 const StableEmptyObject = {};
 
-// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks are still used by the theme
-// We need a fail-safe fallback when the docs plugin is not in use
+// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks
+// are still used by the theme. We need a fail-safe fallback when the docs
+// plugin is not in use
 export const useAllDocsData = (): Record<string, GlobalPluginData> =>
   // useAllPluginInstancesData('docusaurus-plugin-content-docs');
   useGlobalData()['docusaurus-plugin-content-docs'] ?? StableEmptyObject;

package/src/docs.ts

@@ -139,7 +139,8 @@ function doProcessDocMetadata({
   const {
     custom_edit_url: customEditURL,
 
-    // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
@@ -164,7 +165,8 @@ function doProcessDocMetadata({
     throw new Error(`Document id "${baseID}" cannot include slash.`);
   }
 
-  // For autogenerated sidebars, sidebar position can come from filename number prefix or front matter
+  // For autogenerated sidebars, sidebar position can come from filename number
+  // prefix or front matter
   const sidebarPosition: number | undefined =
     frontMatter.sidebar_position ?? numberPrefix;
 
@@ -205,8 +207,9 @@ function doProcessDocMetadata({
     numberPrefixParser: options.numberPrefixParser,
   });
 
-  // Note: the title is used by default for page title, sidebar label, pagination buttons...
-  // frontMatter.title should be used in priority over contentTitle (because it can contain markdown/JSX syntax)
+  // Note: the title is used by default for page title, sidebar label,
+  // pagination buttons... frontMatter.title should be used in priority over
+  // contentTitle (because it can contain markdown/JSX syntax)
   const title: string = frontMatter.title ?? contentTitle ?? baseID;
 
   const description: string = frontMatter.description ?? excerpt ?? '';
@@ -233,9 +236,8 @@ function doProcessDocMetadata({
           ? versionMetadata.versionEditUrlLocalized
           : versionMetadata.versionEditUrl;
       return getEditUrl(relativeFilePath, baseVersionEditUrl);
-    } else {
-      return undefined;
     }
+    return undefined;
   }
 
   // Assign all of object properties during instantiation (if possible) for
@@ -361,9 +363,8 @@ export function getMainDocId({
           doc.id === firstDocIdOfFirstSidebar ||
           doc.unversionedId === firstDocIdOfFirstSidebar,
       )!;
-    } else {
-      return docs[0];
     }
+    return docs[0];
   }
 
   return getMainDoc().unversionedId;
@@ -407,7 +408,8 @@ export function toCategoryIndexMatcherParam({
 }
 
 /**
- * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 export function splitPath(str: string): {
   /**
@@ -428,15 +430,17 @@ export function splitPath(str: string): {
 }
 
 // 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")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 export function getDocIds(doc: DocMetadataBase): [string, string] {
   return [doc.unversionedId, doc.id];
 }
 
 // docs are indexed by both versioned and unversioned ids at the same time
-// TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
-// ("id" should be removed & "versionedId" should be renamed to "id")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 export function createDocsByIdIndex<
   Doc extends {id: string; unversionedId: string},
 >(docs: Doc[]): Record<string, Doc> {

package/src/index.ts

@@ -333,7 +333,7 @@ export default async function pluginContentDocs(
       function createMDXLoaderRule(): RuleSetRule {
         const contentDirs = versionsMetadata.flatMap(getDocsDirPaths);
         return {
-          test: /(\.mdx?)$/,
+          test: /\.mdx?$/i,
           include: contentDirs
             // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
             .map(addTrailingPathSeparator),

package/src/lastUpdate.ts

@@ -10,7 +10,7 @@ import logger from '@docusaurus/logger';
 
 type FileLastUpdateData = {timestamp?: number; author?: string};
 
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
+const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(?<timestamp>\d+),(?<author>.+)$/;
 
 let showedGitRequirementError = false;
 
@@ -25,10 +25,10 @@ export async function getFileLastUpdate(
       return null;
     }
 
-    const temp = str.match(GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX);
-    return !temp || temp.length < 3
-      ? null
-      : {timestamp: +temp[1], author: temp[2]};
+    const temp = str.match(GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX)?.groups;
+    return temp
+      ? {timestamp: Number(temp.timestamp), author: temp.author}
+      : null;
   }
 
   // Wrap in try/catch in case the shell commands fail

package/src/numberPrefix.ts

@@ -8,16 +8,17 @@
 import type {NumberPrefixParser} from '@docusaurus/plugin-content-docs';
 
 // Best-effort to avoid parsing some patterns as number prefix
-const IgnoredPrefixPatterns = (function () {
+const IgnoredPrefixPatterns = (() => {
   // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
   const DateLikePrefixRegex =
-    /^((\d{2}|\d{4})[-_.]\d{2}([-_.](\d{2}|\d{4}))?)(.*)$/;
+    /^(?:\d{2}|\d{4})[-_.]\d{2}(?:[-_.](?:\d{2}|\d{4}))?.*$/;
 
   // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
-  // note: we could try to parse float numbers in filenames but that is probably not worth it
-  // as a version such as "8.0" can be interpreted as both a version and a float
-  // User can configure his own NumberPrefixParser if he wants 8.0 to be interpreted as a float
-  const VersionLikePrefixRegex = /^(\d+[-_.]\d+)(.*)$/;
+  // note: we could try to parse float numbers in filenames but that is
+  // probably not worth it as a version such as "8.0" can be interpreted as both
+  // a version and a float. User can configure her own NumberPrefixParser if
+  // she wants 8.0 to be interpreted as a float
+  const VersionLikePrefixRegex = /^\d+[-_.]\d+.*$/;
 
   return new RegExp(
     `${DateLikePrefixRegex.source}|${VersionLikePrefixRegex.source}`,

package/src/options.ts

@@ -148,8 +148,9 @@ export function validateOptions({
   let options = userOptions;
 
   if (options.sidebarCollapsible === false) {
-    // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't want to have the inconsistency warning
-    // We let options.sidebarCollapsible become the default value for options.sidebarCollapsed
+    // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't
+    // want to have the inconsistency warning. We let options.sidebarCollapsible
+    // become the default value for options.sidebarCollapsed
     if (typeof options.sidebarCollapsed === 'undefined') {
       options = {
         ...options,

package/src/plugin-content-docs.d.ts

@@ -45,7 +45,8 @@ declare module '@docusaurus/plugin-content-docs' {
     sidebarPath?: string | false | undefined;
   };
 
-  // TODO support custom version banner? {type: "error", content: "html content"}
+  // TODO support custom version banner?
+  // {type: "error", content: "html content"}
   export type VersionBanner = 'unreleased' | 'unmaintained';
   export type VersionOptions = {
     path?: string;

package/src/routes.ts

@@ -73,7 +73,8 @@ export async function createCategoryGeneratedIndexRoutes({
       modules: {
         categoryGeneratedIndex: aliasedSource(propData),
       },
-      // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
+      // Same as doc, this sidebar route attribute permits to associate this
+      // subpage to the given sidebar
       ...(sidebar && {sidebar}),
     };
   }
@@ -109,7 +110,8 @@ export async function createDocRoutes({
           content: metadataItem.source,
         },
         // Because the parent (DocPage) comp need to access it easily
-        // This permits to render the sidebar once without unmount/remount when navigating (and preserve sidebar state)
+        // This permits to render the sidebar once without unmount/remount when
+        // navigating (and preserve sidebar state)
         ...(metadataItem.sidebar && {
           sidebar: metadataItem.sidebar,
         }),

package/src/sidebars/generator.ts

@@ -47,7 +47,8 @@ export type CategoryMetadataFile = {
   className?: string;
   link?: SidebarItemCategoryLinkConfig | null;
 
-  // TODO should we allow "items" here? how would this work? would an "autogenerated" type be allowed?
+  // TODO should we allow "items" here? how would this work? would an
+  // "autogenerated" type be allowed?
   // This mkdocs plugin do something like that: https://github.com/lukasgeiter/mkdocs-awesome-pages-plugin/
   // cf comment: https://github.com/facebook/docusaurus/issues/3464#issuecomment-784765199
 };
@@ -56,16 +57,20 @@ type WithPosition<T> = T & {position?: number};
 
 /**
  * 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
+ * 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
  */
 type Dir = {
   [item: string]: Dir | null;
 };
 
-// TODO I now believe we should read all the category metadata files ahead of time: we may need this metadata to customize docs metadata
-// Example use-case being able to disable number prefix parsing at the folder level, or customize the default route path segment for an intermediate directory...
-// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may want to read the metadata as yaml on it
+// TODO I now believe we should read all the category metadata files ahead of
+// time: we may need this metadata to customize docs metadata
+// Example use-case being able to disable number prefix parsing at the folder
+// level, or customize the default base slug for an intermediate directory
+// TODO later if there is `CategoryFolder/with-category-name-doc.md`, we may
+// want to read the metadata as yaml on it
 // see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
 async function readCategoryMetadataFile(
   categoryDirPath: string,
@@ -142,7 +147,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
    * Step 2. Turn the linear file list into a tree structure.
    */
   function treeify(docs: SidebarItemsGeneratorDoc[]): Dir {
-    // Get the category breadcrumb of a doc (relative to the dir of the autogenerated sidebar item)
+    // Get the category breadcrumb of a doc (relative to the dir of the
+    // autogenerated sidebar item)
     // autogenDir=a/b and docDir=a/b/c/d => returns [c, d]
     // autogenDir=a/b and docDir=a/b => returns []
     // TODO: try to use path.relative()
@@ -169,7 +175,7 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   }
 
   /**
-   * Step 3. Recursively transform the tree-like file structure to sidebar items.
+   * Step 3. Recursively transform the tree-like structure to sidebar items.
    * (From a record to an array of items, akin to normalizing shorthand)
    */
   function generateSidebar(fsModel: Dir): Promise<WithPosition<SidebarItem>[]> {
@@ -182,7 +188,8 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         type: 'doc',
         id,
         position,
-        // We don't want these fields to magically appear in the generated sidebar
+        // We don't want these fields to magically appear in the generated
+        // sidebar
         ...(label !== undefined && {label}),
         ...(className !== undefined && {className}),
       };
@@ -225,13 +232,12 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
         if (link !== undefined) {
           if (link && link.type === 'doc') {
             return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
-          } else {
-            // We don't continue for other link types on purpose!
-            // IE if user decide to use type "generated-index", we should not pick a README.md file as the linked doc
-            return undefined;
           }
+          // If a link is explicitly specified, we won't apply conventions
+          return undefined;
         }
-        // Apply default convention to pick index.md, README.md or <categoryName>.md as the category doc
+        // Apply default convention to pick index.md, README.md or
+        // <categoryName>.md as the category doc
         return findConventionalCategoryDocLink()?.id;
       }
 
@@ -279,10 +285,11 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
   }
 
   /**
-   * Step 4. Recursively sort the categories/docs + remove the "position" attribute from final output.
-   * Note: the "position" is only used to sort "inside" a sidebar slice. It is not
-   * used to sort across multiple consecutive sidebar slices (ie a whole Category
-   * composed of multiple autogenerated items)
+   * Step 4. Recursively sort the categories/docs + remove the "position"
+   * attribute from final output. Note: the "position" is only used to sort
+   * "inside" a sidebar slice. It is not used to sort across multiple
+   * consecutive sidebar slices (i.e. a whole category composed of multiple
+   * autogenerated items)
    */
   function sortItems(sidebarItems: WithPosition<SidebarItem>[]): SidebarItem[] {
     const processedSidebarItems = sidebarItems.map((item) => {
@@ -298,7 +305,6 @@ export const DefaultSidebarItemsGenerator: SidebarItemsGenerator = async ({
     return sortedSidebarItems.map(({position, ...item}) => item);
   }
   // TODO: the whole code is designed for pipeline operator
-  // return getAutogenDocs() |> treeify |> await generateSidebar(^) |> sortItems;
   const docs = getAutogenDocs();
   const fsModel = treeify(docs);
   const sidebarWithPosition = await generateSidebar(fsModel);

package/src/sidebars/index.ts

@@ -38,9 +38,9 @@ export function resolveSidebarPathOption(
     : sidebarPathOption;
 }
 
-function loadSidebarsFileUnsafe(
+async function loadSidebarsFileUnsafe(
   sidebarFilePath: string | false | undefined,
-): SidebarsConfig {
+): Promise<SidebarsConfig> {
   // false => no sidebars
   if (sidebarFilePath === false) {
     return DisabledSidebars;
@@ -62,19 +62,19 @@ function loadSidebarsFileUnsafe(
   return importFresh(sidebarFilePath);
 }
 
-export function loadSidebarsFile(
+export async function loadSidebarsFile(
   sidebarFilePath: string | false | undefined,
-): SidebarsConfig {
-  const sidebarsConfig = loadSidebarsFileUnsafe(sidebarFilePath);
+): Promise<SidebarsConfig> {
+  const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
   validateSidebars(sidebarsConfig);
   return sidebarsConfig;
 }
 
-export function loadNormalizedSidebars(
+export async function loadNormalizedSidebars(
   sidebarFilePath: string | false | undefined,
   params: NormalizeSidebarsParams,
-): NormalizedSidebars {
-  return normalizeSidebars(loadSidebarsFile(sidebarFilePath), params);
+): Promise<NormalizedSidebars> {
+  return normalizeSidebars(await loadSidebarsFile(sidebarFilePath), params);
 }
 
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
@@ -87,7 +87,7 @@ export async function loadSidebars(
     version: options.version,
     categoryLabelSlugger: createSlugger(),
   };
-  const normalizedSidebars = loadNormalizedSidebars(
+  const normalizedSidebars = await loadNormalizedSidebars(
     sidebarFilePath,
     normalizeSidebarsParams,
   );

package/src/sidebars/processor.ts

@@ -60,7 +60,8 @@ function toSidebarItemsGeneratorVersion(
   return pick(version, ['versionName', 'contentPath']);
 }
 
-// Handle the generation of autogenerated sidebar items and other post-processing checks
+// Handle the generation of autogenerated sidebar items and other
+// post-processing checks
 async function processSidebar(
   unprocessedSidebar: NormalizedSidebar,
   params: SidebarProcessorParams,
@@ -91,7 +92,8 @@ async function processSidebar(
   async function processAutoGeneratedItem(
     item: SidebarItemAutogenerated,
   ): Promise<SidebarItem[]> {
-    // TODO the returned type can't be trusted in practice (generator can be user-provided)
+    // TODO the returned type can't be trusted in practice (generator can be
+    // user-provided)
     const generatedItems = await sidebarItemsGenerator({
       item,
       numberPrefixParser,
@@ -106,7 +108,8 @@ async function processSidebar(
       normalizeItem(generatedItem, {...params, ...sidebarOptions}),
     );
 
-    // Process again... weird but sidebar item generated might generate some auto-generated items?
+    // Process again... weird but sidebar item generated might generate some
+    // auto-generated items?
     return processItems(generatedItemsNormalized);
   }
 

package/src/sidebars/types.ts

@@ -205,7 +205,8 @@ export type SidebarItemsGenerator = (
 Promise<SidebarItem[]>;
 // Promise<SidebarItemConfig[]>;
 
-// Also inject the default generator to conveniently wrap/enhance/sort the default sidebar gen logic
+// Also inject the default generator to conveniently wrap/enhance/sort the
+// default sidebar gen logic
 // see https://github.com/facebook/docusaurus/issues/4640#issuecomment-822292320
 export type SidebarItemsGeneratorOptionArgs = {
   defaultSidebarItemsGenerator: SidebarItemsGenerator;