@docusaurus/plugin-content-docs 2.0.0-beta.16 → 2.0.0-beta.19

package/lib/options.js

@@ -6,12 +6,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateOptions = exports.OptionsSchema = exports.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = exports.DEFAULT_OPTIONS = void 0;
 const tslib_1 = require("tslib");
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_1 = require("@docusaurus/utils");
-const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-const remark_admonitions_1 = (0, tslib_1.__importDefault)(require("remark-admonitions"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const remark_admonitions_1 = tslib_1.__importDefault(require("remark-admonitions"));
 const generator_1 = require("./sidebars/generator");
 const numberPrefix_1 = require("./numberPrefix");
 exports.DEFAULT_OPTIONS = {
@@ -54,7 +54,7 @@ const VersionOptionsSchema = utils_validation_1.Joi.object({
 const VersionsOptionsSchema = utils_validation_1.Joi.object()
     .pattern(utils_validation_1.Joi.string().required(), VersionOptionsSchema)
     .default(exports.DEFAULT_OPTIONS.versions);
-exports.OptionsSchema = utils_validation_1.Joi.object({
+const OptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.path),
     editUrl: utils_validation_1.Joi.alternatives().try(utils_validation_1.URISchema, utils_validation_1.Joi.function()),
     editCurrentVersion: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.editCurrentVersion),
@@ -64,6 +64,7 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         // .allow('') ""
         .default(exports.DEFAULT_OPTIONS.routeBasePath),
     tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
+    // @ts-expect-error: deprecated
     homePageId: utils_validation_1.Joi.any().forbidden().messages({
         'any.unknown': 'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
     }),
@@ -121,7 +122,7 @@ function validateOptions({ validate, options: userOptions, }) {
             };
         }
     }
-    const normalizedOptions = validate(exports.OptionsSchema, options);
+    const normalizedOptions = validate(OptionsSchema, options);
     if (normalizedOptions.admonitions) {
         normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([
             [remark_admonitions_1.default, normalizedOptions.admonitions],

package/lib/props.d.ts

@@ -4,12 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { LoadedVersion, VersionTag, DocMetadata } from './types';
-import type { PropSidebars, PropVersionMetadata, PropTagDocList } from '@docusaurus/plugin-content-docs';
+import type { VersionTag } from './types';
+import type { PropSidebars, PropVersionMetadata, PropTagDocList, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';
 export declare function toSidebarsProp(loadedVersion: LoadedVersion): PropSidebars;
 export declare function toVersionMetadataProp(pluginId: string, loadedVersion: LoadedVersion): PropVersionMetadata;
 export declare function toTagDocListProp({ allTagsPath, tag, docs, }: {
     allTagsPath: string;
     tag: VersionTag;
-    docs: Pick<DocMetadata, 'id' | 'title' | 'description' | 'permalink'>[];
+    docs: DocMetadata[];
 }): PropTagDocList;

package/lib/props.js

@@ -8,7 +8,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
 const tslib_1 = require("tslib");
-const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
 function toSidebarsProp(loadedVersion) {
     const docsById = (0, docs_1.createDocsByIdIndex)(loadedVersion.docs);
@@ -22,7 +22,6 @@ Available document ids are:
         return docMetadata;
     }
     const convertDocLink = (item) => {
-        var _a;
         const docMetadata = getDocById(item.id);
         const { title, permalink, frontMatter: { sidebar_label: sidebarLabel }, } = docMetadata;
         return {
@@ -30,12 +29,12 @@ Available document ids are:
             label: sidebarLabel || item.label || title,
             href: permalink,
             className: item.className,
-            customProps: (_a = item.customProps) !== null && _a !== void 0 ? _a : docMetadata.frontMatter.sidebar_custom_props,
+            customProps: item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
             docId: docMetadata.unversionedId,
         };
     };
     function getCategoryLinkHref(link) {
-        switch (link === null || link === void 0 ? void 0 : link.type) {
+        switch (link?.type) {
             case 'doc':
                 return getDocById(link.id).permalink;
             case 'generated-index':
@@ -82,10 +81,10 @@ function toVersionMetadataProp(pluginId, loadedVersion) {
     return {
         pluginId,
         version: loadedVersion.versionName,
-        label: loadedVersion.versionLabel,
-        banner: loadedVersion.versionBanner,
-        badge: loadedVersion.versionBadge,
-        className: loadedVersion.versionClassName,
+        label: loadedVersion.label,
+        banner: loadedVersion.banner,
+        badge: loadedVersion.badge,
+        className: loadedVersion.className,
         isLast: loadedVersion.isLast,
         docsSidebars: toSidebarsProp(loadedVersion),
         docs: toVersionDocsProp(loadedVersion),
@@ -105,10 +104,11 @@ function toTagDocListProp({ allTagsPath, tag, docs, }) {
         }));
     }
     return {
-        name: tag.name,
+        label: tag.label,
         permalink: tag.permalink,
-        docs: toDocListProp(),
         allTagsPath,
+        count: tag.docIds.length,
+        items: toDocListProp(),
     };
 }
 exports.toTagDocListProp = toTagDocListProp;

package/lib/routes.d.ts

@@ -5,9 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
-import type { DocMetadata, LoadedVersion } from './types';
+import type { FullVersion } from './types';
+import type { DocMetadata } from '@docusaurus/plugin-content-docs';
 export declare function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }: {
-    version: LoadedVersion;
+    version: FullVersion;
     actions: PluginContentLoadedActions;
     docCategoryGeneratedIndexComponent: string;
     aliasedSource: (str: string) => string;
@@ -17,8 +18,8 @@ export declare function createDocRoutes({ docs, actions, docItemComponent, }: {
     actions: PluginContentLoadedActions;
     docItemComponent: string;
 }): Promise<RouteConfig[]>;
-export declare function createVersionRoutes({ loadedVersion, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }: {
-    loadedVersion: LoadedVersion;
+export declare function createVersionRoutes({ version, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }: {
+    version: FullVersion;
     actions: PluginContentLoadedActions;
     docLayoutComponent: string;
     docItemComponent: string;

package/lib/routes.js

@@ -10,27 +10,15 @@ exports.createVersionRoutes = exports.createDocRoutes = exports.createCategoryGe
 const tslib_1 = require("tslib");
 const utils_1 = require("@docusaurus/utils");
 const props_1 = require("./props");
-const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }) {
     const slugs = (0, utils_1.createSlugger)();
     async function createCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
-        const { sidebar, title, description, slug, permalink, previous, next, image, keywords, } = categoryGeneratedIndex;
-        const propFileName = slugs.slug(`${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
-        const prop = {
-            title,
-            description,
-            slug,
-            permalink,
-            image,
-            keywords,
-            navigation: {
-                previous,
-                next,
-            },
-        };
+        const { sidebar, ...prop } = categoryGeneratedIndex;
+        const propFileName = slugs.slug(`${version.path}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
         const propData = await actions.createData(`${(0, utils_1.docuHash)(`category/${propFileName}`)}.json`, JSON.stringify(prop, null, 2));
         return {
-            path: permalink,
+            path: categoryGeneratedIndex.permalink,
             component: docCategoryGeneratedIndexComponent,
             exact: true,
             modules: {
@@ -68,8 +56,8 @@ async function createDocRoutes({ docs, actions, docItemComponent, }) {
     }));
 }
 exports.createDocRoutes = createDocRoutes;
-async function createVersionRoutes({ loadedVersion, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }) {
-    async function doCreateVersionRoutes(version) {
+async function createVersionRoutes({ version, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }) {
+    async function doCreateVersionRoutes() {
         const versionMetadata = (0, props_1.toVersionMetadataProp)(pluginId, version);
         const versionMetadataPropPath = await actions.createData(`${(0, utils_1.docuHash)(`version-${version.versionName}-metadata-prop`)}.json`, JSON.stringify(versionMetadata, null, 2));
         async function createVersionSubRoutes() {
@@ -86,12 +74,10 @@ async function createVersionRoutes({ loadedVersion, actions, docItemComponent, d
             return routes.sort((a, b) => a.path.localeCompare(b.path));
         }
         actions.addRoute({
-            path: version.versionPath,
-            // allow matching /docs/* as well
+            path: version.path,
+            // Allow matching /docs/* since this is the wrapping route
             exact: false,
-            // main docs component (DocPage)
             component: docLayoutComponent,
-            // sub-routes for each doc
             routes: await createVersionSubRoutes(),
             modules: {
                 versionMetadata: aliasedSource(versionMetadataPropPath),
@@ -100,10 +86,10 @@ async function createVersionRoutes({ loadedVersion, actions, docItemComponent, d
         });
     }
     try {
-        return await doCreateVersionRoutes(loadedVersion);
+        return await doCreateVersionRoutes();
     }
     catch (err) {
-        logger_1.default.error `Can't create version routes for version name=${loadedVersion.versionName}`;
+        logger_1.default.error `Can't create version routes for version name=${version.versionName}`;
         throw err;
     }
 }

package/lib/server-export.d.ts

@@ -5,4 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 export { CURRENT_VERSION_NAME, VERSIONED_DOCS_DIR, VERSIONED_SIDEBARS_DIR, VERSIONS_JSON_FILE, } from './constants';
-export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, getVersionsFilePath, readVersionsFile, readVersionNames, } from './versions';
+export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, } from './versions';
+export { readVersionNames } from './versions/files';

package/lib/server-export.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionBanner = exports.getVersionBadge = exports.getDefaultVersionBanner = exports.filterVersions = exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
+exports.readVersionNames = exports.getVersionBanner = exports.getVersionBadge = exports.getDefaultVersionBanner = exports.filterVersions = exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
 // APIs available to Node.js
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "CURRENT_VERSION_NAME", { enumerable: true, get: function () { return constants_1.CURRENT_VERSION_NAME; } });
@@ -18,6 +18,5 @@ Object.defineProperty(exports, "filterVersions", { enumerable: true, get: functi
 Object.defineProperty(exports, "getDefaultVersionBanner", { enumerable: true, get: function () { return versions_1.getDefaultVersionBanner; } });
 Object.defineProperty(exports, "getVersionBadge", { enumerable: true, get: function () { return versions_1.getVersionBadge; } });
 Object.defineProperty(exports, "getVersionBanner", { enumerable: true, get: function () { return versions_1.getVersionBanner; } });
-Object.defineProperty(exports, "getVersionsFilePath", { enumerable: true, get: function () { return versions_1.getVersionsFilePath; } });
-Object.defineProperty(exports, "readVersionsFile", { enumerable: true, get: function () { return versions_1.readVersionsFile; } });
-Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return versions_1.readVersionNames; } });
+var files_1 = require("./versions/files");
+Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return files_1.readVersionNames; } });

package/lib/sidebars/generator.js

@@ -8,14 +8,12 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultSidebarItemsGenerator = exports.CategoryMetadataFilenamePattern = exports.CategoryMetadataFilenameBase = void 0;
 const tslib_1 = require("tslib");
-const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
-const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
+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('/'));
@@ -29,7 +27,9 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
     const getDoc = (docId) => {
         const doc = findDoc(docId);
         if (!doc) {
-            throw new Error(`Can't find any doc with id=${docId}.\nAvailable doc ids:\n- ${Object.keys(docsById).join('\n- ')}`);
+            throw new Error(`Can't find any doc with ID ${docId}.
+Available doc IDs:
+- ${Object.keys(docsById).join('\n- ')}`);
         }
         return doc;
     };
@@ -41,9 +41,9 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
             return (
             // Doc at the root of the autogenerated sidebar dir
             doc.sourceDirName === autogenDir ||
-                // autogen dir is . and doc is in subfolder
+                // Autogen dir is . and doc is in subfolder
                 autogenDir === '.' ||
-                // autogen dir is not . and doc is in subfolder
+                // Autogen dir is not . and doc is in subfolder
                 // "api/myDoc" startsWith "api/" (note "api2/myDoc" is not included)
                 doc.sourceDirName.startsWith((0, utils_1.addTrailingSlash)(autogenDir)));
         }
@@ -72,14 +72,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,24 +90,22 @@ 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) {
-            var _a, _b;
-            const categoryMetadata = categoriesMetadata[(0, utils_1.posixPath)(path_1.default.join(autogenDir, fullPath))];
-            const className = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.className;
-            const { filename, numberPrefix } = numberPrefixParser(folderName);
-            const allItems = await Promise.all(Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`)));
+        function createCategoryItem(dir, fullPath, folderName) {
+            const categoryMetadata = categoriesMetadata[path_1.default.posix.join(autogenDir, fullPath)];
+            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) {
@@ -120,48 +120,64 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
                     return isCategoryIndex((0, docs_1.toCategoryIndexMatcherParam)(doc));
                 });
             }
-            function getCategoryLinkedDocId() {
-                var _a, _b;
-                const link = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
-                if (link !== undefined) {
-                    if (link && link.type === 'doc') {
-                        return ((_a = findDocByLocalId(link.id)) === null || _a === void 0 ? void 0 : _a.id) || getDoc(link.id).id;
-                    }
+            // In addition to the ID, this function also retrieves metadata of the
+            // linked doc that could be used as fallback values for category metadata
+            function getCategoryLinkedDocMetadata() {
+                const link = categoryMetadata?.link;
+                if (link !== undefined && link?.type !== 'doc') {
                     // 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
-                return (_b = findConventionalCategoryDocLink()) === null || _b === void 0 ? void 0 : _b.id;
+                const id = link
+                    ? findDocByLocalId(link.id)?.id ?? getDoc(link.id).id
+                    : findConventionalCategoryDocLink()?.id;
+                if (!id) {
+                    return undefined;
+                }
+                const doc = getDoc(id);
+                return {
+                    id,
+                    position: doc.sidebarPosition,
+                    label: doc.frontMatter.sidebar_label ?? doc.title,
+                    customProps: doc.frontMatter.sidebar_custom_props,
+                    className: doc.frontMatter.sidebar_class_name,
+                };
             }
-            const categoryLinkedDocId = getCategoryLinkedDocId();
-            const link = categoryLinkedDocId
+            const categoryLinkedDoc = getCategoryLinkedDocMetadata();
+            const link = categoryLinkedDoc
                 ? {
                     type: 'doc',
-                    id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
+                    id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
                 }
-                : categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
+                : categoryMetadata?.link;
             // If a doc is linked, remove it from the category subItems
-            const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDocId));
+            const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id));
+            const className = categoryMetadata?.className ?? categoryLinkedDoc?.className;
+            const customProps = categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+            const { filename, numberPrefix } = numberPrefixParser(folderName);
             return {
                 type: 'category',
-                label: (_a = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.label) !== null && _a !== void 0 ? _a : filename,
-                collapsible: categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.collapsible,
-                collapsed: categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.collapsed,
-                position: (_b = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.position) !== null && _b !== void 0 ? _b : numberPrefix,
+                label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
+                collapsible: categoryMetadata?.collapsible,
+                collapsed: categoryMetadata?.collapsed,
+                position: categoryMetadata?.position ??
+                    categoryLinkedDoc?.position ??
+                    numberPrefix,
+                source: folderName,
+                ...(customProps !== undefined && { customProps }),
                 ...(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"
@@ -177,13 +193,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/lib/sidebars/index.js

@@ -8,18 +8,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadSidebars = exports.loadSidebarsFileUnsafe = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
 const tslib_1 = require("tslib");
-const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
-const import_fresh_1 = (0, tslib_1.__importDefault)(require("import-fresh"));
+const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
+const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
 const validation_1 = require("./validation");
 const normalization_1 = require("./normalization");
 const processor_1 = require("./processor");
 const postProcessor_1 = require("./postProcessor");
-const path_1 = (0, tslib_1.__importDefault)(require("path"));
+const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
-const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
-const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
-const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
-const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const js_yaml_1 = tslib_1.__importDefault(require("js-yaml"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
 exports.DefaultSidebars = {
     defaultSidebar: [
         {
@@ -30,7 +30,6 @@ exports.DefaultSidebars = {
 };
 exports.DisabledSidebars = {};
 // If a path is provided, make it absolute
-// use this before loadSidebars()
 function resolveSidebarPathOption(siteDir, sidebarPathOption) {
     return sidebarPathOption
         ? path_1.default.resolve(siteDir, sidebarPathOption)
@@ -43,7 +42,7 @@ async function readCategoriesMetadata(contentPath) {
     });
     const categoryToFile = lodash_1.default.groupBy(categoryFiles, path_1.default.dirname);
     return (0, combine_promises_1.default)(lodash_1.default.mapValues(categoryToFile, async (files, folder) => {
-        const [filePath] = files;
+        const filePath = files[0];
         if (files.length > 1) {
             logger_1.default.warn `There are more than one category metadata files for path=${folder}: ${files.join(', ')}. The behavior is undetermined.`;
         }
@@ -76,13 +75,18 @@ async function loadSidebarsFileUnsafe(sidebarFilePath) {
     return (0, import_fresh_1.default)(sidebarFilePath);
 }
 exports.loadSidebarsFileUnsafe = loadSidebarsFileUnsafe;
-// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 async function loadSidebars(sidebarFilePath, options) {
-    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
-    const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
-    (0, validation_1.validateSidebars)(normalizedSidebars);
-    const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
-    const processedSidebars = await (0, processor_1.processSidebars)(normalizedSidebars, categoriesMetadata, options);
-    return (0, postProcessor_1.postProcessSidebars)(processedSidebars, options);
+    try {
+        const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+        const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
+        (0, validation_1.validateSidebars)(normalizedSidebars);
+        const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
+        const processedSidebars = await (0, processor_1.processSidebars)(normalizedSidebars, categoriesMetadata, options);
+        return (0, postProcessor_1.postProcessSidebars)(processedSidebars, options);
+    }
+    catch (err) {
+        logger_1.default.error `Sidebars file at path=${sidebarFilePath} failed to be loaded.`;
+        throw err;
+    }
 }
 exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.js

@@ -9,8 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeSidebars = exports.normalizeItem = void 0;
 const tslib_1 = require("tslib");
 const utils_1 = require("./utils");
-const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
-const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 function normalizeCategoriesShorthand(sidebar) {
     return Object.entries(sidebar).map(([label, items]) => ({
         type: 'category',
@@ -42,7 +42,7 @@ function normalizeItem(item) {
 exports.normalizeItem = normalizeItem;
 function normalizeSidebar(sidebar, place) {
     if (!Array.isArray(sidebar) && !(0, utils_1.isCategoriesShorthand)(sidebar)) {
-        throw new Error(logger_1.default.interpolate `Invalid sidebar items collection code=${JSON.stringify(sidebar)} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See path=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`);
+        throw new Error(logger_1.default.interpolate `Invalid sidebar items collection code=${JSON.stringify(sidebar)} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`);
     }
     const normalizedSidebar = Array.isArray(sidebar)
         ? sidebar

package/lib/sidebars/postProcessor.js

@@ -9,14 +9,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.postProcessSidebars = void 0;
 const tslib_1 = require("tslib");
 const utils_1 = require("@docusaurus/utils");
-const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 function normalizeCategoryLink(category, params) {
-    var _a, _b;
-    if (((_a = category.link) === null || _a === void 0 ? void 0 : _a.type) === 'generated-index') {
-        // default slug logic can be improved
+    if (category.link?.type === 'generated-index') {
+        // Default slug logic can be improved
         const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`;
-        const slug = (_b = category.link.slug) !== null && _b !== void 0 ? _b : getDefaultSlug();
-        const permalink = (0, utils_1.normalizeUrl)([params.version.versionPath, slug]);
+        const slug = category.link.slug ?? getDefaultSlug();
+        const permalink = (0, utils_1.normalizeUrl)([params.version.path, slug]);
         return {
             ...category.link,
             slug,
@@ -26,12 +25,11 @@ function normalizeCategoryLink(category, params) {
     return category.link;
 }
 function postProcessSidebarItem(item, params) {
-    var _a, _b;
     if (item.type === 'category') {
         const category = {
             ...item,
-            collapsed: (_a = item.collapsed) !== null && _a !== void 0 ? _a : params.sidebarOptions.sidebarCollapsed,
-            collapsible: (_b = item.collapsible) !== null && _b !== void 0 ? _b : params.sidebarOptions.sidebarCollapsible,
+            collapsed: item.collapsed ?? params.sidebarOptions.sidebarCollapsed,
+            collapsible: item.collapsible ?? params.sidebarOptions.sidebarCollapsible,
             link: normalizeCategoryLink(item, params),
             items: item.items.map((subItem) => postProcessSidebarItem(subItem, params)),
         };
@@ -41,22 +39,17 @@ function postProcessSidebarItem(item, params) {
             if (!category.link) {
                 throw new Error(`Sidebar category ${item.label} has neither any subitem nor a link. This makes this item not able to link to anything.`);
             }
-            switch (category.link.type) {
-                case 'doc':
-                    return {
-                        type: 'doc',
-                        label: category.label,
-                        id: category.link.id,
-                    };
-                case 'generated-index':
-                    return {
-                        type: 'link',
-                        label: category.label,
-                        href: category.link.permalink,
-                    };
-                default:
-                    throw new Error('Unexpected sidebar category link type');
-            }
+            return category.link.type === 'doc'
+                ? {
+                    type: 'doc',
+                    label: category.label,
+                    id: category.link.id,
+                }
+                : {
+                    type: 'link',
+                    label: category.label,
+                    href: category.link.permalink,
+                };
         }
         // A non-collapsible category can't be collapsed!
         if (category.collapsible === false) {

package/lib/sidebars/processor.d.ts

@@ -5,4 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { NormalizedSidebars, ProcessedSidebars, SidebarProcessorParams, CategoryMetadataFile } from './types';
-export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: Record<string, CategoryMetadataFile>, params: SidebarProcessorParams): Promise<ProcessedSidebars>;
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: {
+    [filePath: string]: CategoryMetadataFile;
+}, params: SidebarProcessorParams): Promise<ProcessedSidebars>;