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

package/lib/server-export.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * 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;
+// 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; } });
+Object.defineProperty(exports, "VERSIONED_DOCS_DIR", { enumerable: true, get: function () { return constants_1.VERSIONED_DOCS_DIR; } });
+Object.defineProperty(exports, "VERSIONED_SIDEBARS_DIR", { enumerable: true, get: function () { return constants_1.VERSIONED_SIDEBARS_DIR; } });
+Object.defineProperty(exports, "VERSIONS_JSON_FILE", { enumerable: true, get: function () { return constants_1.VERSIONS_JSON_FILE; } });
+var versions_1 = require("./versions");
+Object.defineProperty(exports, "filterVersions", { enumerable: true, get: function () { return versions_1.filterVersions; } });
+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; } });

package/lib/sidebars/generator.d.ts

@@ -4,15 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SidebarItemsGenerator, SidebarItemCategoryLinkConfig } from './types';
+import type { SidebarItemsGenerator } from './types';
 export declare const CategoryMetadataFilenameBase = "_category_";
 export declare const CategoryMetadataFilenamePattern = "_category_.{json,yml,yaml}";
-export declare type CategoryMetadataFile = {
-    label?: string;
-    position?: number;
-    collapsed?: boolean;
-    collapsible?: boolean;
-    className?: string;
-    link?: SidebarItemCategoryLinkConfig;
-};
 export declare const DefaultSidebarItemsGenerator: SidebarItemsGenerator;

package/lib/sidebars/generator.js

@@ -8,44 +8,22 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultSidebarItemsGenerator = exports.CategoryMetadataFilenamePattern = exports.CategoryMetadataFilenameBase = void 0;
 const tslib_1 = require("tslib");
-const lodash_1 = require("lodash");
+const lodash_1 = (0, 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 fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
-const js_yaml_1 = (0, tslib_1.__importDefault)(require("js-yaml"));
-const validation_1 = require("./validation");
 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 (0, lodash_1.last)(docId.split('/'));
+    return lodash_1.default.last(docId.split('/'));
 }
 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
-// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-async function readCategoryMetadataFile(categoryDirPath) {
-    async function tryReadFile(filePath) {
-        const contentString = await fs_extra_1.default.readFile(filePath, { encoding: 'utf8' });
-        const unsafeContent = js_yaml_1.default.load(contentString);
-        try {
-            return (0, validation_1.validateCategoryMetadataFile)(unsafeContent);
-        }
-        catch (e) {
-            logger_1.default.error `The docs sidebar category metadata file path=${filePath} looks invalid!`;
-            throw e;
-        }
-    }
-    const filePath = await (0, utils_1.findAsyncSequential)(['.json', '.yml', '.yaml'].map((ext) => (0, utils_1.posixPath)(path_1.default.join(categoryDirPath, `${exports.CategoryMetadataFilenameBase}${ext}`))), fs_extra_1.default.pathExists);
-    return filePath ? tryReadFile(filePath) : null;
-}
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, item: { dirName: autogenDir }, categoriesMetadata, }) => {
     const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
     const findDoc = (docId) => docsById[docId];
     const getDoc = (docId) => {
@@ -79,7 +57,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 +84,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,15 +94,15 @@ 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 }),
             };
         }
         async function createCategoryItem(dir, fullPath, folderName) {
-            var _a, _b, _c, _d;
-            const categoryPath = path_1.default.join(version.contentPath, autogenDir, fullPath);
-            const categoryMetadata = await readCategoryMetadataFile(categoryPath);
+            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}`)));
@@ -144,17 +123,15 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
             function getCategoryLinkedDocId() {
                 var _a, _b;
                 const link = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
-                if (link) {
-                    if (link.type === 'doc') {
+                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;
                     }
-                    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();
@@ -163,16 +140,15 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
                     type: 'doc',
                     id: categoryLinkedDocId, // We "remap" a potentially "local id" to a "qualified id"
                 }
-                : // TODO typing issue
-                    categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
+                : categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
             // If a doc is linked, remove it from the category subItems
             const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDocId));
             return {
                 type: 'category',
                 label: (_a = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.label) !== null && _a !== void 0 ? _a : filename,
-                collapsible: (_b = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.collapsible) !== null && _b !== void 0 ? _b : options.sidebarCollapsible,
-                collapsed: (_c = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.collapsed) !== null && _c !== void 0 ? _c : options.sidebarCollapsed,
-                position: (_d = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.position) !== null && _d !== void 0 ? _d : numberPrefix,
+                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,
                 ...(className !== undefined && { className }),
                 items,
                 ...(link && { link }),
@@ -188,10 +164,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) => {
@@ -200,11 +177,10 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
             }
             return item;
         });
-        const sortedSidebarItems = (0, lodash_1.sortBy)(processedSidebarItems, (item) => item.position);
+        const sortedSidebarItems = lodash_1.default.sortBy(processedSidebarItems, (item) => item.position);
         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

@@ -4,13 +4,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { SidebarsConfig, Sidebars, NormalizedSidebars } from './types';
-import type { NormalizeSidebarsParams } from '../types';
-import { type SidebarProcessorParams } from './processor';
+import type { SidebarsConfig, Sidebars, SidebarProcessorParams } from './types';
 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 loadSidebarsFileUnsafe(sidebarFilePath: string | false | undefined): Promise<SidebarsConfig>;
 export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -6,15 +6,20 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadSidebars = exports.loadNormalizedSidebars = exports.loadSidebarsFile = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
+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 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 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"));
 exports.DefaultSidebars = {
     defaultSidebar: [
         {
@@ -32,7 +37,27 @@ function resolveSidebarPathOption(siteDir, sidebarPathOption) {
         : sidebarPathOption;
 }
 exports.resolveSidebarPathOption = resolveSidebarPathOption;
-function loadSidebarsFileUnsafe(sidebarFilePath) {
+async function readCategoriesMetadata(contentPath) {
+    const categoryFiles = await (0, utils_1.Globby)('**/_category_.{json,yml,yaml}', {
+        cwd: 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;
+        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.`;
+        }
+        const content = await fs_extra_1.default.readFile(path_1.default.join(contentPath, filePath), 'utf-8');
+        try {
+            return (0, validation_1.validateCategoryMetadataFile)(js_yaml_1.default.load(content));
+        }
+        catch (err) {
+            logger_1.default.error `The docs sidebar category metadata file path=${filePath} looks invalid!`;
+            throw err;
+        }
+    }));
+}
+async function loadSidebarsFileUnsafe(sidebarFilePath) {
     // false => no sidebars
     if (sidebarFilePath === false) {
         return exports.DisabledSidebars;
@@ -44,30 +69,20 @@ function loadSidebarsFileUnsafe(sidebarFilePath) {
     // Non-existent sidebars file: no sidebars
     // Note: this edge case can happen on versioned docs, not current version
     // We avoid creating empty versioned sidebars file with the CLI
-    if (!fs_extra_1.default.existsSync(sidebarFilePath)) {
+    if (!(await fs_extra_1.default.pathExists(sidebarFilePath))) {
         return exports.DisabledSidebars;
     }
     // 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);
-    (0, validation_1.validateSidebars)(sidebarsConfig);
-    return sidebarsConfig;
-}
-exports.loadSidebarsFile = loadSidebarsFile;
-function loadNormalizedSidebars(sidebarFilePath, params) {
-    return (0, normalization_1.normalizeSidebars)(loadSidebarsFile(sidebarFilePath), params);
-}
-exports.loadNormalizedSidebars = loadNormalizedSidebars;
+exports.loadSidebarsFileUnsafe = loadSidebarsFileUnsafe;
 // Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
 async function loadSidebars(sidebarFilePath, options) {
-    const normalizeSidebarsParams = {
-        ...options.sidebarOptions,
-        version: options.version,
-        categoryLabelSlugger: (0, utils_1.createSlugger)(),
-    };
-    const normalizedSidebars = loadNormalizedSidebars(sidebarFilePath, normalizeSidebarsParams);
-    return (0, processor_1.processSidebars)(normalizedSidebars, 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);
 }
 exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.d.ts

@@ -4,11 +4,10 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { NormalizeSidebarsParams } from '../types';
 import type { NormalizedSidebarItem, NormalizedSidebars, SidebarItemConfig, SidebarsConfig } from './types';
 /**
  * Normalizes recursively item and all its children. Ensures that at the end
  * each item will be an object with the corresponding type.
  */
-export declare function normalizeItem(item: SidebarItemConfig, options: NormalizeSidebarsParams): NormalizedSidebarItem[];
-export declare function normalizeSidebars(sidebars: SidebarsConfig, params: NormalizeSidebarsParams): NormalizedSidebars;
+export declare function normalizeItem(item: SidebarItemConfig): NormalizedSidebarItem[];
+export declare function normalizeSidebars(sidebars: SidebarsConfig): NormalizedSidebars;

package/lib/sidebars/normalization.js

@@ -7,29 +7,13 @@
  */
 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 = require("lodash");
-const utils_2 = require("@docusaurus/utils");
-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
-        const getDefaultSlug = () => `/category/${params.categoryLabelSlugger.slug(category.label)}`;
-        const slug = (_b = category.link.slug) !== null && _b !== void 0 ? _b : getDefaultSlug();
-        const permalink = (0, utils_2.normalizeUrl)([params.version.versionPath, slug]);
-        return {
-            ...category.link,
-            slug,
-            permalink,
-        };
-    }
-    return category.link;
-}
-function normalizeCategoriesShorthand(sidebar, options) {
+const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
+const logger_1 = (0, tslib_1.__importDefault)(require("@docusaurus/logger"));
+function normalizeCategoriesShorthand(sidebar) {
     return Object.entries(sidebar).map(([label, items]) => ({
         type: 'category',
-        collapsed: options.sidebarCollapsed,
-        collapsible: options.sidebarCollapsible,
         label,
         items,
     }));
@@ -38,40 +22,34 @@ function normalizeCategoriesShorthand(sidebar, options) {
  * Normalizes recursively item and all its children. Ensures that at the end
  * each item will be an object with the corresponding type.
  */
-function normalizeItem(item, options) {
-    var _a, _b, _c;
+function normalizeItem(item) {
     if (typeof item === 'string') {
-        return [
-            {
-                type: 'doc',
-                id: item,
-            },
-        ];
+        return [{ type: 'doc', id: item }];
     }
     if ((0, utils_1.isCategoriesShorthand)(item)) {
-        return normalizeCategoriesShorthand(item, options).flatMap((subItem) => normalizeItem(subItem, options));
+        // This will never throw anyways
+        return normalizeSidebar(item, 'sidebar items slice');
     }
     if (item.type === 'category') {
-        const link = normalizeCategoryLink(item, options);
         const normalizedCategory = {
             ...item,
-            link,
-            items: ((_a = item.items) !== null && _a !== void 0 ? _a : []).flatMap((subItem) => normalizeItem(subItem, options)),
-            collapsible: (_b = item.collapsible) !== null && _b !== void 0 ? _b : options.sidebarCollapsible,
-            collapsed: (_c = item.collapsed) !== null && _c !== void 0 ? _c : options.sidebarCollapsed,
+            items: normalizeSidebar(item.items, logger_1.default.interpolate `code=${'items'} of the category name=${item.label}`),
         };
         return [normalizedCategory];
     }
     return [item];
 }
 exports.normalizeItem = normalizeItem;
-function normalizeSidebar(sidebar, options) {
+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.`);
+    }
     const normalizedSidebar = Array.isArray(sidebar)
         ? sidebar
-        : normalizeCategoriesShorthand(sidebar, options);
-    return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem, options));
+        : normalizeCategoriesShorthand(sidebar);
+    return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
 }
-function normalizeSidebars(sidebars, params) {
-    return (0, lodash_1.mapValues)(sidebars, (items) => normalizeSidebar(items, params));
+function normalizeSidebars(sidebars) {
+    return lodash_1.default.mapValues(sidebars, (sidebar, id) => normalizeSidebar(sidebar, logger_1.default.interpolate `sidebar name=${id}`));
 }
 exports.normalizeSidebars = normalizeSidebars;

package/lib/sidebars/postProcessor.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { Sidebars, SidebarProcessorParams, ProcessedSidebars } from './types';
+export declare function postProcessSidebars(sidebars: ProcessedSidebars, params: SidebarProcessorParams): Sidebars;

package/lib/sidebars/postProcessor.js

@@ -0,0 +1,72 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+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"));
+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
+        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]);
+        return {
+            ...category.link,
+            slug,
+            permalink,
+        };
+    }
+    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,
+            link: normalizeCategoryLink(item, params),
+            items: item.items.map((subItem) => postProcessSidebarItem(subItem, params)),
+        };
+        // If the current category doesn't have subitems, we render a normal link
+        // instead.
+        if (category.items.length === 0) {
+            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');
+            }
+        }
+        // A non-collapsible category can't be collapsed!
+        if (category.collapsible === false) {
+            category.collapsed = false;
+        }
+        return category;
+    }
+    return item;
+}
+function postProcessSidebars(sidebars, params) {
+    return lodash_1.default.mapValues(sidebars, (sidebar) => sidebar.map((item) => postProcessSidebarItem(item, params)));
+}
+exports.postProcessSidebars = postProcessSidebars;

package/lib/sidebars/processor.d.ts

@@ -4,16 +4,5 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { DocMetadataBase, VersionMetadata } from '../types';
-import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption } from './types';
-import type { Slugger } from '@docusaurus/utils';
-import type { NumberPrefixParser, SidebarOptions } from '@docusaurus/plugin-content-docs';
-export declare type SidebarProcessorParams = {
-    sidebarItemsGenerator: SidebarItemsGeneratorOption;
-    numberPrefixParser: NumberPrefixParser;
-    docs: DocMetadataBase[];
-    version: VersionMetadata;
-    categoryLabelSlugger: Slugger;
-    sidebarOptions: SidebarOptions;
-};
-export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, params: SidebarProcessorParams): Promise<Sidebars>;
+import type { NormalizedSidebars, ProcessedSidebars, SidebarProcessorParams, CategoryMetadataFile } from './types';
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, categoriesMetadata: Record<string, CategoryMetadataFile>, params: SidebarProcessorParams): Promise<ProcessedSidebars>;

package/lib/sidebars/processor.js

@@ -8,14 +8,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.processSidebars = void 0;
 const tslib_1 = require("tslib");
-const utils_1 = require("./utils");
 const generator_1 = require("./generator");
-const lodash_1 = require("lodash");
+const validation_1 = require("./validation");
+const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
 const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
-const normalization_1 = require("./normalization");
 const docs_1 = require("../docs");
 function toSidebarItemsGeneratorDoc(doc) {
-    return (0, lodash_1.pick)(doc, [
+    return lodash_1.default.pick(doc, [
         'id',
         'unversionedId',
         'frontMatter',
@@ -25,24 +24,18 @@ function toSidebarItemsGeneratorDoc(doc) {
     ]);
 }
 function toSidebarItemsGeneratorVersion(version) {
-    return (0, lodash_1.pick)(version, ['versionName', 'contentPath']);
+    return lodash_1.default.pick(version, ['versionName', 'contentPath']);
 }
-// Handle the generation of autogenerated sidebar items and other post-processing checks
-async function processSidebar(unprocessedSidebar, params) {
+// Handle the generation of autogenerated sidebar items and other
+// post-processing checks
+async function processSidebar(unprocessedSidebar, categoriesMetadata, params) {
     const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, } = params;
     // Just a minor lazy transformation optimization
-    const getSidebarItemsGeneratorDocsAndVersion = (0, lodash_1.memoize)(() => ({
+    const getSidebarItemsGeneratorDocsAndVersion = lodash_1.default.memoize(() => ({
         docs: docs.map(toSidebarItemsGeneratorDoc),
         version: toSidebarItemsGeneratorVersion(version),
     }));
-    async function processCategoryItem(item) {
-        return {
-            ...item,
-            items: (await Promise.all(item.items.map(processItem))).flat(),
-        };
-    }
     async function processAutoGeneratedItem(item) {
-        // TODO the returned type can't be trusted in practice (generator can be user-provided)
         const generatedItems = await sidebarItemsGenerator({
             item,
             numberPrefixParser,
@@ -50,15 +43,22 @@ async function processSidebar(unprocessedSidebar, params) {
             isCategoryIndex: docs_1.isCategoryIndex,
             ...getSidebarItemsGeneratorDocsAndVersion(),
             options: sidebarOptions,
+            categoriesMetadata,
         });
-        // 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?
-        return processItems(generatedItemsNormalized);
+        // Process again... weird but sidebar item generated might generate some
+        // auto-generated items?
+        // TODO repeatedly process & unwrap autogenerated items until there are no
+        // more autogenerated items, or when loop count (e.g. 10) is reached
+        return processItems(generatedItems);
     }
     async function processItem(item) {
         if (item.type === 'category') {
-            return [await processCategoryItem(item)];
+            return [
+                {
+                    ...item,
+                    items: (await Promise.all(item.items.map(processItem))).flat(),
+                },
+            ];
         }
         if (item.type === 'autogenerated') {
             return processAutoGeneratedItem(item);
@@ -69,19 +69,11 @@ async function processSidebar(unprocessedSidebar, params) {
         return (await Promise.all(items.map(processItem))).flat();
     }
     const processedSidebar = await processItems(unprocessedSidebar);
-    const fixSidebarItemInconsistencies = (item) => {
-        // A non-collapsible category can't be collapsed!
-        if (item.type === 'category' && !item.collapsible && item.collapsed) {
-            return {
-                ...item,
-                collapsed: false,
-            };
-        }
-        return item;
-    };
-    return (0, utils_1.transformSidebarItems)(processedSidebar, fixSidebarItemInconsistencies);
+    return processedSidebar;
 }
-async function processSidebars(unprocessedSidebars, params) {
-    return (0, combine_promises_1.default)((0, lodash_1.mapValues)(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, params)));
+async function processSidebars(unprocessedSidebars, categoriesMetadata, params) {
+    const processedSidebars = await (0, combine_promises_1.default)(lodash_1.default.mapValues(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, categoriesMetadata, params)));
+    (0, validation_1.validateSidebars)(processedSidebars);
+    return processedSidebars;
 }
 exports.processSidebars = processSidebars;