@docusaurus/plugin-content-docs 0.0.0-4523 → 0.0.0-4527

package/lib/cli.d.ts

@@ -5,4 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { PathOptions, SidebarOptions } from '@docusaurus/plugin-content-docs';
-export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): void;
+export declare function cliDocsVersionCommand(version: string | null | undefined, siteDir: string, pluginId: string, options: PathOptions & SidebarOptions): Promise<void>;

package/lib/cli.js

@@ -14,11 +14,13 @@ const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const sidebars_1 = require("./sidebars");
 const utils_1 = require("@docusaurus/utils");
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
+async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }) {
     // 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 = (0, sidebars_1.loadSidebarsFile)(sidebarPath);
-    // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
+    // 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 (0, sidebars_1.loadSidebarsFile)(sidebarPath);
+    // 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) {
         const versionedSidebarsDir = (0, versions_1.getVersionedSidebarsDirPath)(siteDir, pluginId);
@@ -28,7 +30,7 @@ function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, version, }
     }
 }
 // Tests depend on non-default export for mocking.
-function cliDocsVersionCommand(version, siteDir, pluginId, options) {
+async function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     // It wouldn't be very user-friendly to show a [default] log prefix,
     // so we use [docs] instead of [default]
     const pluginIdLogPrefix = pluginId === utils_1.DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
@@ -71,7 +73,7 @@ function cliDocsVersionCommand(version, siteDir, pluginId, options) {
     else {
         throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
     }
-    createVersionedSidebarFile({
+    await createVersionedSidebarFile({
         siteDir,
         pluginId,
         version,

package/lib/client/docsClientUtils.js

@@ -14,7 +14,7 @@ const router_1 = require("@docusaurus/router");
 // it is useful to support multiple docs plugin instances
 function getActivePlugin(allPluginDatas, pathname, options = {}) {
     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]) => !!(0, router_1.matchPath)(pathname, {
         path: pluginData.path,
@@ -39,7 +39,7 @@ exports.getLatestVersion = getLatestVersion;
 const getActiveVersion = (data, pathname) => {
     const lastVersion = (0, exports.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/lib/client/globalDataHooks.js

@@ -11,11 +11,12 @@ const tslib_1 = require("tslib");
 const router_1 = require("@docusaurus/router");
 const useGlobalData_1 = (0, tslib_1.__importStar)(require("@docusaurus/useGlobalData"));
 const docsClientUtils_1 = require("./docsClientUtils");
-// 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
 const useAllDocsData = () => { var _a; 
 // useAllPluginInstancesData('docusaurus-plugin-content-docs');
 return (_a = (0, useGlobalData_1.default)()['docusaurus-plugin-content-docs']) !== null && _a !== void 0 ? _a : StableEmptyObject; };

package/lib/docs.d.ts

@@ -32,7 +32,8 @@ export declare function getMainDocId({ docs, sidebarsUtils, }: {
 export declare const isCategoryIndex: CategoryIndexMatcher;
 export declare function toCategoryIndexMatcherParam({ source, sourceDirName, }: Pick<DocMetadataBase, 'source' | 'sourceDirName'>): CategoryIndexMatcherParam;
 /**
- * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 export declare function splitPath(str: string): {
     /**

package/lib/docs.js

@@ -65,7 +65,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     const { frontMatter: unsafeFrontMatter, contentTitle, excerpt, } = (0, utils_1.parseMarkdownString)(content);
     const frontMatter = (0, docFrontMatter_1.validateDocFrontMatter)(unsafeFrontMatter);
     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;
     // ex: api/plugins/myDoc -> myDoc
@@ -81,7 +82,8 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
     if (baseID.includes('/')) {
         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 = (_b = frontMatter.sidebar_position) !== null && _b !== void 0 ? _b : numberPrefix;
     // TODO legacy retrocompatibility
     // The same doc in 2 distinct version could keep the same id,
@@ -114,8 +116,9 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
         stripDirNumberPrefixes: parseNumberPrefixes,
         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 = (_d = (_c = frontMatter.title) !== null && _c !== void 0 ? _c : contentTitle) !== null && _d !== void 0 ? _d : baseID;
     const description = (_f = (_e = frontMatter.description) !== null && _e !== void 0 ? _e : excerpt) !== null && _f !== void 0 ? _f : '';
     const permalink = (0, utils_1.normalizeUrl)([versionMetadata.versionPath, docSlug]);
@@ -137,9 +140,7 @@ function doProcessDocMetadata({ docFile, versionMetadata, context, options, }) {
                 : versionMetadata.versionEditUrl;
             return (0, utils_1.getEditUrl)(relativeFilePath, baseVersionEditUrl);
         }
-        else {
-            return undefined;
-        }
+        return undefined;
     }
     // Assign all of object properties during instantiation (if possible) for
     // NodeJS optimization.
@@ -225,9 +226,7 @@ function getMainDocId({ docs, sidebarsUtils, }) {
             return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar ||
                 doc.unversionedId === firstDocIdOfFirstSidebar);
         }
-        else {
-            return docs[0];
-        }
+        return docs[0];
     }
     return getMainDoc().unversionedId;
 }
@@ -262,7 +261,8 @@ function toCategoryIndexMatcherParam({ source, sourceDirName, }) {
 }
 exports.toCategoryIndexMatcherParam = toCategoryIndexMatcherParam;
 /**
- * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 function splitPath(str) {
     return {
@@ -273,15 +273,17 @@ function splitPath(str) {
 }
 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")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 function getDocIds(doc) {
     return [doc.unversionedId, doc.id];
 }
 exports.getDocIds = getDocIds;
 // 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")
 function createDocsByIdIndex(docs) {
     return {
         ...(0, lodash_1.keyBy)(docs, (doc) => doc.unversionedId),

package/lib/index.js

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

package/lib/lastUpdate.js

@@ -10,20 +10,21 @@ exports.getFileLastUpdate = void 0;
 const tslib_1 = require("tslib");
 const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
 const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
+const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(?<timestamp>\d+),(?<author>.+)$/;
 let showedGitRequirementError = false;
 async function getFileLastUpdate(filePath) {
     if (!filePath) {
         return null;
     }
     function getTimestampAndAuthor(str) {
+        var _a;
         if (!str) {
             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 = (_a = str.match(GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX)) === null || _a === void 0 ? void 0 : _a.groups;
+        return temp
+            ? { timestamp: Number(temp.timestamp), author: temp.author }
+            : null;
     }
     // Wrap in try/catch in case the shell commands fail
     // (e.g. project doesn't use Git, etc).

package/lib/numberPrefix.js

@@ -8,14 +8,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.stripPathNumberPrefixes = exports.stripNumberPrefix = exports.DisabledNumberPrefixParser = exports.DefaultNumberPrefixParser = void 0;
 // 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}))?)(.*)$/;
+    const DateLikePrefixRegex = /^(?:\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}`);
 })();
 const NumberPrefixRegex = /^(?<numberPrefix>\d+)(?<separator>\s*[-_.]+\s*)(?<suffix>.*)$/;

package/lib/options.js

@@ -102,8 +102,9 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
 function validateOptions({ validate, options: userOptions, }) {
     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/lib/routes.js

@@ -36,7 +36,8 @@ async function createCategoryGeneratedIndexRoutes({ version, actions, docCategor
             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 }),
         };
     }
@@ -57,7 +58,8 @@ async function createDocRoutes({ docs, actions, docItemComponent, }) {
                 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/lib/sidebars/generator.js

@@ -25,9 +25,12 @@ function getLocalDocId(docId) {
 }
 exports.CategoryMetadataFilenameBase = '_category_';
 exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
-// 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) {
     async function tryReadFile(filePath) {
@@ -79,7 +82,8 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
      * Step 2. Turn the linear file list into a tree structure.
      */
     function treeify(docs) {
-        // 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()
@@ -105,7 +109,7 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
         return treeRoot;
     }
     /**
-     * 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) {
@@ -115,7 +119,8 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
                 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 }),
             };
@@ -148,13 +153,11 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
                     if (link && link.type === 'doc') {
                         return ((_a = findDocByLocalId(link.id)) === null || _a === void 0 ? void 0 : _a.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 (_b = findConventionalCategoryDocLink()) === null || _b === void 0 ? void 0 : _b.id;
             }
             const categoryLinkedDocId = getCategoryLinkedDocId();
@@ -188,10 +191,11 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
         return Promise.all(Object.entries(fsModel).map(([key, content]) => dirToItem(content, key, key)));
     }
     /**
-     * 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) {
         const processedSidebarItems = sidebarItems.map((item) => {
@@ -204,7 +208,6 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
         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/lib/sidebars/index.d.ts

@@ -11,6 +11,6 @@ import type { PluginOptions } from '@docusaurus/plugin-content-docs';
 export declare const DefaultSidebars: SidebarsConfig;
 export declare const DisabledSidebars: SidebarsConfig;
 export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
-export declare function loadSidebarsFile(sidebarFilePath: string | false | undefined): SidebarsConfig;
-export declare function loadNormalizedSidebars(sidebarFilePath: string | false | undefined, params: NormalizeSidebarsParams): NormalizedSidebars;
+export declare function loadSidebarsFile(sidebarFilePath: string | false | undefined): Promise<SidebarsConfig>;
+export declare function loadNormalizedSidebars(sidebarFilePath: string | false | undefined, params: NormalizeSidebarsParams): Promise<NormalizedSidebars>;
 export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -32,7 +32,7 @@ function resolveSidebarPathOption(siteDir, sidebarPathOption) {
         : sidebarPathOption;
 }
 exports.resolveSidebarPathOption = resolveSidebarPathOption;
-function loadSidebarsFileUnsafe(sidebarFilePath) {
+async function loadSidebarsFileUnsafe(sidebarFilePath) {
     // false => no sidebars
     if (sidebarFilePath === false) {
         return exports.DisabledSidebars;
@@ -50,14 +50,14 @@ function loadSidebarsFileUnsafe(sidebarFilePath) {
     // We don't want sidebars to be cached because of hot reloading.
     return (0, import_fresh_1.default)(sidebarFilePath);
 }
-function loadSidebarsFile(sidebarFilePath) {
-    const sidebarsConfig = loadSidebarsFileUnsafe(sidebarFilePath);
+async function loadSidebarsFile(sidebarFilePath) {
+    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
     (0, validation_1.validateSidebars)(sidebarsConfig);
     return sidebarsConfig;
 }
 exports.loadSidebarsFile = loadSidebarsFile;
-function loadNormalizedSidebars(sidebarFilePath, params) {
-    return (0, normalization_1.normalizeSidebars)(loadSidebarsFile(sidebarFilePath), params);
+async function loadNormalizedSidebars(sidebarFilePath, params) {
+    return (0, normalization_1.normalizeSidebars)(await loadSidebarsFile(sidebarFilePath), params);
 }
 exports.loadNormalizedSidebars = loadNormalizedSidebars;
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
@@ -67,7 +67,7 @@ async function loadSidebars(sidebarFilePath, options) {
         version: options.version,
         categoryLabelSlugger: (0, utils_1.createSlugger)(),
     };
-    const normalizedSidebars = loadNormalizedSidebars(sidebarFilePath, normalizeSidebarsParams);
+    const normalizedSidebars = await loadNormalizedSidebars(sidebarFilePath, normalizeSidebarsParams);
     return (0, processor_1.processSidebars)(normalizedSidebars, options);
 }
 exports.loadSidebars = loadSidebars;

package/lib/sidebars/processor.js

@@ -27,7 +27,8 @@ function toSidebarItemsGeneratorDoc(doc) {
 function toSidebarItemsGeneratorVersion(version) {
     return (0, lodash_1.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, params) {
     const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, } = params;
     // Just a minor lazy transformation optimization
@@ -42,7 +43,8 @@ async function processSidebar(unprocessedSidebar, params) {
         };
     }
     async function processAutoGeneratedItem(item) {
-        // 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,
@@ -53,7 +55,8 @@ async function processSidebar(unprocessedSidebar, params) {
         });
         // TODO validate generated items: user can generate bad items
         const generatedItemsNormalized = generatedItems.flatMap((generatedItem) => (0, normalization_1.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);
     }
     async function processItem(item) {

package/lib/sidebars/utils.js

@@ -26,8 +26,11 @@ function transformSidebarItems(sidebar, updateFn) {
     return sidebar.map(transformRecursive);
 }
 exports.transformSidebarItems = transformSidebarItems;
-// Flatten sidebar items into a single flat array (containing categories/docs on the same level)
-// /!\ order matters (useful for next/prev nav), top categories appear before their child elements
+/**
+ * Flatten sidebar items into a single flat array (containing categories/docs on
+ * the same level). Order matters (useful for next/prev nav), top categories
+ * appear before their child elements
+ */
 function flattenSidebarItems(items) {
     function flattenRecursive(item) {
         return item.type === 'category'
@@ -114,29 +117,27 @@ function createSidebarsUtils(sidebars) {
             docId = versionedId;
             sidebarName = getSidebarNameByDocId(docId);
         }
-        if (sidebarName) {
-            if (!sidebarNameToNavigationItems[sidebarName]) {
-                throw new Error(`Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`);
+        if (!sidebarName) {
+            return emptySidebarNavigation();
+        }
+        if (!sidebarNameToNavigationItems[sidebarName]) {
+            throw new Error(`Doc with ID ${docId} wants to display sidebar ${sidebarName} but a sidebar with this name doesn't exist`);
+        }
+        const navigationItems = sidebarNameToNavigationItems[sidebarName];
+        const currentItemIndex = navigationItems.findIndex((item) => {
+            if (item.type === 'doc') {
+                return item.id === docId;
             }
-            const navigationItems = sidebarNameToNavigationItems[sidebarName];
-            const currentItemIndex = navigationItems.findIndex((item) => {
-                if (item.type === 'doc') {
-                    return item.id === docId;
-                }
-                if (item.type === 'category' && item.link.type === 'doc') {
-                    return item.link.id === docId;
-                }
-                return false;
-            });
-            if (currentItemIndex === -1) {
-                return { sidebarName, next: undefined, previous: undefined };
+            if (item.type === 'category' && item.link.type === 'doc') {
+                return item.link.id === docId;
             }
-            const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
-            return { sidebarName, previous, next };
-        }
-        else {
-            return emptySidebarNavigation();
+            return false;
+        });
+        if (currentItemIndex === -1) {
+            return { sidebarName, next: undefined, previous: undefined };
         }
+        const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
+        return { sidebarName, previous, next };
     }
     function getCategoryGeneratedIndexList() {
         return Object.values(sidebarNameToNavigationItems)
@@ -148,8 +149,10 @@ function createSidebarsUtils(sidebars) {
             return [];
         });
     }
-    // We identity the category generated index by its permalink (should be unique)
-    // More reliable than using object identity
+    /**
+     * We identity the category generated index by its permalink (should be
+     * unique). More reliable than using object identity
+     */
     function getCategoryGeneratedIndexNavigation(categoryGeneratedIndexPermalink) {
         var _a;
         function isCurrentCategoryGeneratedIndexItem(item) {
@@ -159,15 +162,13 @@ function createSidebarsUtils(sidebars) {
                 item.link.permalink === categoryGeneratedIndexPermalink);
         }
         const sidebarName = (_a = Object.entries(sidebarNameToNavigationItems).find(([, navigationItems]) => navigationItems.find(isCurrentCategoryGeneratedIndexItem))) === null || _a === void 0 ? void 0 : _a[0];
-        if (sidebarName) {
-            const navigationItems = sidebarNameToNavigationItems[sidebarName];
-            const currentItemIndex = navigationItems.findIndex(isCurrentCategoryGeneratedIndexItem);
-            const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
-            return { sidebarName, previous, next };
-        }
-        else {
+        if (!sidebarName) {
             return emptySidebarNavigation();
         }
+        const navigationItems = sidebarNameToNavigationItems[sidebarName];
+        const currentItemIndex = navigationItems.findIndex(isCurrentCategoryGeneratedIndexItem);
+        const { previous, next } = (0, utils_1.getElementsAround)(navigationItems, currentItemIndex);
+        return { sidebarName, previous, next };
     }
     function checkSidebarsDocIds(validDocIds, sidebarFilePath) {
         const allSidebarDocIds = Object.values(sidebarNameToDocIds).flat();
@@ -207,11 +208,9 @@ Available document ids are:
                         label: item.label,
                     };
                 }
-                else {
-                    const firstSubItem = getFirstLink(item.items);
-                    if (firstSubItem) {
-                        return firstSubItem;
-                    }
+                const firstSubItem = getFirstLink(item.items);
+                if (firstSubItem) {
+                    return firstSubItem;
                 }
             }
         }
@@ -243,20 +242,6 @@ function toNavigationLink(navigationItem, docsById) {
         }
         return doc;
     }
-    function handleCategory(category) {
-        if (category.link.type === 'doc') {
-            return toDocNavigationLink(getDocById(category.link.id));
-        }
-        else if (category.link.type === 'generated-index') {
-            return {
-                title: category.label,
-                permalink: category.link.permalink,
-            };
-        }
-        else {
-            throw new Error('unexpected category link type');
-        }
-    }
     if (!navigationItem) {
         return undefined;
     }
@@ -264,10 +249,17 @@ function toNavigationLink(navigationItem, docsById) {
         return toDocNavigationLink(getDocById(navigationItem.id));
     }
     else if (navigationItem.type === 'category') {
-        return handleCategory(navigationItem);
-    }
-    else {
-        throw new Error('unexpected navigation item');
+        if (navigationItem.link.type === 'doc') {
+            return toDocNavigationLink(getDocById(navigationItem.link.id));
+        }
+        else if (navigationItem.link.type === 'generated-index') {
+            return {
+                title: navigationItem.label,
+                permalink: navigationItem.link.permalink,
+            };
+        }
+        throw new Error('unexpected category link type');
     }
+    throw new Error('unexpected navigation item');
 }
 exports.toNavigationLink = toNavigationLink;

package/lib/sidebars/validation.js

@@ -10,7 +10,8 @@ exports.validateCategoryMetadataFile = exports.validateSidebars = void 0;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_1 = require("./utils");
 // NOTE: we don't add any default values during validation on purpose!
-// Config types are exposed to users for typechecking and we use the same type in normalization
+// Config types are exposed to users for typechecking and we use the same type
+// in normalization
 const sidebarItemBaseSchema = utils_validation_1.Joi.object({
     className: utils_validation_1.Joi.string(),
     customProps: utils_validation_1.Joi.object().unknown(),
@@ -19,7 +20,7 @@ const sidebarItemAutogeneratedSchema = sidebarItemBaseSchema.append({
     type: 'autogenerated',
     dirName: utils_validation_1.Joi.string()
         .required()
-        .pattern(/^[^/](.*[^/])?$/)
+        .pattern(/^[^/](?:.*[^/])?$/)
         .message('"dirName" must be a dir path relative to the docs folder root, and should not start or end with slash'),
 });
 const sidebarItemDocSchema = sidebarItemBaseSchema.append({
@@ -50,7 +51,8 @@ const sidebarItemCategoryLinkSchema = utils_validation_1.Joi.object()
             then: utils_validation_1.Joi.object({
                 type: 'generated-index',
                 slug: utils_validation_1.Joi.string().optional(),
-                // permalink: Joi.string().optional(), // No, this one is not in the user config, only in the normalized version
+                // This one is not in the user config, only in the normalized version
+                // permalink: Joi.string().optional(),
                 title: utils_validation_1.Joi.string().optional(),
                 description: utils_validation_1.Joi.string().optional(),
                 image: utils_validation_1.Joi.string().optional(),
@@ -107,7 +109,8 @@ function validateSidebarItem(item) {
         return;
     }
     // TODO: remove once with proper Joi support
-    // Because we can't use Joi to validate nested items (see above), we do it manually
+    // Because we can't use Joi to validate nested items (see above), we do it
+    // manually
     if ((0, utils_1.isCategoriesShorthand)(item)) {
         Object.values(item).forEach((category) => category.forEach(validateSidebarItem));
     }