@docusaurus/plugin-content-docs 0.0.0-4546 → 0.0.0-4550

package/lib/cli.js

@@ -18,7 +18,8 @@ async function createVersionedSidebarFile({ siteDir, pluginId, sidebarPath, vers
     // 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 = await (0, sidebars_1.loadSidebarsFile)(sidebarPath);
+    // We don't validate here, assuming the user has already built the version
+    const sidebars = await (0, sidebars_1.loadSidebarsFileUnsafe)(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;

package/lib/sidebars/generator.js

@@ -23,7 +23,7 @@ function getLocalDocId(docId) {
 exports.CategoryMetadataFilenameBase = '_category_';
 exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
 // Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
-const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryIndex, docs: allDocs, options, item: { dirName: autogenDir }, categoriesMetadata, }) => {
+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) => {
@@ -101,7 +101,7 @@ const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, isCategoryInde
             };
         }
         async function createCategoryItem(dir, fullPath, folderName) {
-            var _a, _b, _c, _d;
+            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);
@@ -140,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 }),

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): Promise<SidebarsConfig>;
-export declare function loadNormalizedSidebars(sidebarFilePath: string | false | undefined, params: NormalizeSidebarsParams): Promise<NormalizedSidebars>;
-export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: Omit<SidebarProcessorParams, 'categoriesMetadata'>): Promise<Sidebars>;
+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,13 +6,14 @@
  * 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"));
@@ -74,25 +75,14 @@ async function loadSidebarsFileUnsafe(sidebarFilePath) {
     // We don't want sidebars to be cached because of hot reloading.
     return (0, import_fresh_1.default)(sidebarFilePath);
 }
-async function loadSidebarsFile(sidebarFilePath) {
-    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
-    (0, validation_1.validateSidebars)(sidebarsConfig);
-    return sidebarsConfig;
-}
-exports.loadSidebarsFile = loadSidebarsFile;
-async function loadNormalizedSidebars(sidebarFilePath, params) {
-    return (0, normalization_1.normalizeSidebars)(await 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 = await loadNormalizedSidebars(sidebarFilePath, normalizeSidebarsParams);
+    const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+    const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
+    (0, validation_1.validateSidebars)(normalizedSidebars);
     const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
-    return (0, processor_1.processSidebars)(normalizedSidebars, { ...options, categoriesMetadata });
+    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

@@ -9,27 +9,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.normalizeSidebars = exports.normalizeItem = void 0;
 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) {
+function normalizeCategoriesShorthand(sidebar) {
     return Object.entries(sidebar).map(([label, items]) => ({
         type: 'category',
-        collapsed: options.sidebarCollapsed,
-        collapsible: options.sidebarCollapsible,
         label,
         items,
     }));
@@ -38,8 +20,7 @@ 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 [
             {
@@ -49,29 +30,30 @@ function normalizeItem(item, options) {
         ];
     }
     if ((0, utils_1.isCategoriesShorthand)(item)) {
-        return normalizeCategoriesShorthand(item, options).flatMap((subItem) => normalizeItem(subItem, options));
+        return normalizeCategoriesShorthand(item).flatMap((subItem) => normalizeItem(subItem));
     }
     if (item.type === 'category') {
-        const link = normalizeCategoryLink(item, options);
+        if (typeof item.items !== 'undefined' && typeof item.items !== 'object') {
+            throw new Error(`Invalid category ${JSON.stringify(item)}: items must be an array of sidebar items or a category shorthand`);
+        }
         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: Array.isArray(item.items)
+                ? item.items.flatMap((subItem) => normalizeItem(subItem))
+                : normalizeCategoriesShorthand(item.items).flatMap((subItem) => normalizeItem(subItem)),
         };
         return [normalizedCategory];
     }
     return [item];
 }
 exports.normalizeItem = normalizeItem;
-function normalizeSidebar(sidebar, options) {
+function normalizeSidebar(sidebar) {
     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 (0, lodash_1.mapValues)(sidebars, normalizeSidebar);
 }
 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,71 @@
+"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 utils_1 = require("@docusaurus/utils");
+const lodash_1 = 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 (0, lodash_1.mapValues)(sidebars, (sidebar) => sidebar.map((item) => postProcessSidebarItem(item, params)));
+}
+exports.postProcessSidebars = postProcessSidebars;

package/lib/sidebars/processor.d.ts

@@ -4,17 +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, CategoryMetadataFile } 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;
-    categoriesMetadata: Record<string, CategoryMetadataFile>;
-};
-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,11 +8,10 @@
 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 validation_1 = require("./validation");
 const lodash_1 = 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, [
@@ -29,22 +28,14 @@ function toSidebarItemsGeneratorVersion(version) {
 }
 // Handle the generation of autogenerated sidebar items and other
 // post-processing checks
-async function processSidebar(unprocessedSidebar, params) {
-    const { sidebarItemsGenerator, numberPrefixParser, docs, version, sidebarOptions, categoriesMetadata, } = params;
+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)(() => ({
         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,
@@ -54,41 +45,20 @@ async function processSidebar(unprocessedSidebar, params) {
             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);
+        // 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') {
-            // If the current category doesn't have subitems, we render a normal doc link instead.
-            if (item.items.length === 0) {
-                if (!item.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 (item.link.type) {
-                    case 'doc':
-                        return [
-                            {
-                                type: 'doc',
-                                label: item.label,
-                                id: item.link.id,
-                            },
-                        ];
-                    case 'generated-index':
-                        return [
-                            {
-                                type: 'link',
-                                label: item.label,
-                                href: item.link.permalink,
-                            },
-                        ];
-                    default:
-                        throw new Error('Unexpected sidebar category link type');
-                }
-            }
-            return [await processCategoryItem(item)];
+            return [
+                {
+                    ...item,
+                    items: (await Promise.all(item.items.map(processItem))).flat(),
+                },
+            ];
         }
         if (item.type === 'autogenerated') {
             return processAutoGeneratedItem(item);
@@ -99,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)((0, lodash_1.mapValues)(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, categoriesMetadata, params)));
+    (0, validation_1.validateSidebars)(processedSidebars);
+    return processedSidebars;
 }
 exports.processSidebars = processSidebars;

package/lib/sidebars/types.d.ts

@@ -7,6 +7,7 @@
 import type { Optional, Required } from 'utility-types';
 import type { DocMetadataBase, VersionMetadata } from '../types';
 import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher } from '@docusaurus/plugin-content-docs';
+import type { Slugger } from '@docusaurus/utils';
 declare type Expand<T extends Record<string, unknown>> = {
     [P in keyof T]: T[P];
 };
@@ -63,26 +64,35 @@ export declare type SidebarItemCategoryLinkGeneratedIndex = {
 export declare type SidebarItemCategoryLinkConfig = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndexConfig;
 export declare type SidebarItemCategoryLink = SidebarItemCategoryLinkDoc | SidebarItemCategoryLinkGeneratedIndex;
 export declare type SidebarItemCategoryConfig = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
-    items: SidebarItemConfig[];
+    items: SidebarCategoriesShorthand | SidebarItemConfig[];
     link?: SidebarItemCategoryLinkConfig;
 }>;
 export declare type SidebarCategoriesShorthand = {
-    [sidebarCategory: string]: SidebarItemConfig[];
+    [sidebarCategory: string]: SidebarCategoriesShorthand | SidebarItemConfig[];
 };
 export declare type SidebarItemConfig = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | SidebarItemAutogenerated | SidebarItemCategoryConfig | string | SidebarCategoriesShorthand;
 export declare type SidebarConfig = SidebarCategoriesShorthand | SidebarItemConfig[];
 export declare type SidebarsConfig = {
     [sidebarId: string]: SidebarConfig;
 };
-export declare type NormalizedSidebarItemCategory = Expand<SidebarItemCategoryBase & {
+export declare type NormalizedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
     items: NormalizedSidebarItem[];
-    link?: SidebarItemCategoryLink;
+    link?: SidebarItemCategoryLinkConfig;
 }>;
 export declare type NormalizedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | NormalizedSidebarItemCategory | SidebarItemAutogenerated;
 export declare type NormalizedSidebar = NormalizedSidebarItem[];
 export declare type NormalizedSidebars = {
     [sidebarId: string]: NormalizedSidebar;
 };
+export declare type ProcessedSidebarItemCategory = Expand<Optional<SidebarItemCategoryBase, 'collapsed' | 'collapsible'> & {
+    items: ProcessedSidebarItem[];
+    link?: SidebarItemCategoryLinkConfig;
+}>;
+export declare type ProcessedSidebarItem = SidebarItemDoc | SidebarItemHtml | SidebarItemLink | ProcessedSidebarItemCategory;
+export declare type ProcessedSidebar = ProcessedSidebarItem[];
+export declare type ProcessedSidebars = {
+    [sidebarId: string]: ProcessedSidebar;
+};
 export declare type SidebarItemCategory = Expand<SidebarItemCategoryBase & {
     items: SidebarItem[];
     link?: SidebarItemCategoryLink;
@@ -139,9 +149,17 @@ export declare type SidebarItemsGeneratorArgs = {
     categoriesMetadata: Record<string, CategoryMetadataFile>;
     options: SidebarOptions;
 };
-export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<SidebarItem[]>;
+export declare type SidebarItemsGenerator = (generatorArgs: SidebarItemsGeneratorArgs) => Promise<NormalizedSidebar>;
 export declare type SidebarItemsGeneratorOptionArgs = {
     defaultSidebarItemsGenerator: SidebarItemsGenerator;
 } & SidebarItemsGeneratorArgs;
-export declare type SidebarItemsGeneratorOption = (generatorArgs: SidebarItemsGeneratorOptionArgs) => Promise<SidebarItem[]>;
+export declare type SidebarItemsGeneratorOption = (generatorArgs: SidebarItemsGeneratorOptionArgs) => Promise<NormalizedSidebarItem[]>;
+export declare type SidebarProcessorParams = {
+    sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    numberPrefixParser: NumberPrefixParser;
+    docs: DocMetadataBase[];
+    version: VersionMetadata;
+    categoryLabelSlugger: Slugger;
+    sidebarOptions: SidebarOptions;
+};
 export {};

package/lib/sidebars/validation.d.ts

@@ -4,6 +4,6 @@
  * 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, CategoryMetadataFile } from './types';
-export declare function validateSidebars(sidebars: unknown): asserts sidebars is SidebarsConfig;
+import type { NormalizedSidebars, CategoryMetadataFile } from './types';
+export declare function validateSidebars(sidebars: Record<string, unknown>): asserts sidebars is NormalizedSidebars;
 export declare function validateCategoryMetadataFile(unsafeContent: unknown): CategoryMetadataFile;

package/lib/sidebars/validation.js

@@ -8,7 +8,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 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
@@ -31,7 +30,7 @@ const sidebarItemDocSchema = sidebarItemBaseSchema.append({
 const sidebarItemHtmlSchema = sidebarItemBaseSchema.append({
     type: 'html',
     value: utils_validation_1.Joi.string().required(),
-    defaultStyle: utils_validation_1.Joi.boolean().default(false),
+    defaultStyle: utils_validation_1.Joi.boolean(),
 });
 const sidebarItemLinkSchema = sidebarItemBaseSchema.append({
     type: 'link',
@@ -65,23 +64,23 @@ const sidebarItemCategoryLinkSchema = utils_validation_1.Joi.object()
             }),
         },
         {
-            is: utils_validation_1.Joi.string().required(),
+            is: utils_validation_1.Joi.required(),
             then: utils_validation_1.Joi.forbidden().messages({
                 'any.unknown': 'Unknown sidebar category link type "{.type}".',
             }),
         },
     ],
-})
-    .id('sidebarCategoryLinkSchema');
+});
 const sidebarItemCategorySchema = sidebarItemBaseSchema.append({
     type: 'category',
     label: utils_validation_1.Joi.string()
         .required()
         .messages({ 'any.unknown': '"label" must be a string' }),
-    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
     items: utils_validation_1.Joi.array()
         .required()
         .messages({ 'any.unknown': '"items" must be an array' }),
+    // TODO: Joi doesn't allow mutual recursion. See https://github.com/sideway/joi/issues/2611
+    // .items(Joi.link('#sidebarItemSchema')),
     link: sidebarItemCategoryLinkSchema,
     collapsed: utils_validation_1.Joi.boolean().messages({
         'any.unknown': '"collapsed" must be a boolean',
@@ -90,8 +89,7 @@ const sidebarItemCategorySchema = sidebarItemBaseSchema.append({
         'any.unknown': '"collapsible" must be a boolean',
     }),
 });
-const sidebarItemSchema = utils_validation_1.Joi.object()
-    .when('.type', {
+const sidebarItemSchema = utils_validation_1.Joi.object().when('.type', {
     switch: [
         { is: 'link', then: sidebarItemLinkSchema },
         {
@@ -108,33 +106,20 @@ const sidebarItemSchema = utils_validation_1.Joi.object()
             }),
         },
     ],
-})
-    .id('sidebarItemSchema');
+});
+// .id('sidebarItemSchema');
 function validateSidebarItem(item) {
-    if (typeof item === 'string') {
-        return;
-    }
     // TODO: remove once with proper Joi support
     // 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));
-    }
-    else {
-        utils_validation_1.Joi.assert(item, sidebarItemSchema);
-        if (item.type === 'category') {
-            item.items.forEach(validateSidebarItem);
-        }
+    utils_validation_1.Joi.assert(item, sidebarItemSchema);
+    if (item.type === 'category') {
+        item.items.forEach(validateSidebarItem);
     }
 }
 function validateSidebars(sidebars) {
     Object.values(sidebars).forEach((sidebar) => {
-        if (Array.isArray(sidebar)) {
-            sidebar.forEach(validateSidebarItem);
-        }
-        else {
-            validateSidebarItem(sidebar);
-        }
+        sidebar.forEach(validateSidebarItem);
     });
 }
 exports.validateSidebars = validateSidebars;

package/lib/types.d.ts

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { Sidebars } from './sidebars/types';
-import type { Tag, FrontMatterTag, Slugger } from '@docusaurus/utils';
+import type { Tag, FrontMatterTag } from '@docusaurus/utils';
 import type { BrokenMarkdownLink as IBrokenMarkdownLink, ContentPaths } from '@docusaurus/utils/lib/markdownLinks';
-import type { VersionBanner, SidebarOptions } from '@docusaurus/plugin-content-docs';
+import type { VersionBanner } from '@docusaurus/plugin-content-docs';
 export declare type DocFile = {
     contentPath: string;
     filePath: string;
@@ -29,10 +29,6 @@ export declare type VersionMetadata = ContentPaths & {
     sidebarFilePath: string | false | undefined;
     routePriority: number | undefined;
 };
-export declare type NormalizeSidebarsParams = SidebarOptions & {
-    version: VersionMetadata;
-    categoryLabelSlugger: Slugger;
-};
 export declare type LastUpdateData = {
     lastUpdatedAt?: number;
     formattedLastUpdatedAt?: string;