@docusaurus/plugin-content-docs 2.0.0-beta.12faed89d → 2.0.0-beta.13

package/lib/props.js

@@ -6,30 +6,51 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
+exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
 const lodash_1 = require("lodash");
+const docs_1 = require("./docs");
 function toSidebarsProp(loadedVersion) {
-    const docsById = lodash_1.keyBy(loadedVersion.docs, (doc) => doc.id);
-    const convertDocLink = (item) => {
-        const docId = item.id;
+    const docsById = (0, docs_1.createDocsByIdIndex)(loadedVersion.docs);
+    function getDocById(docId) {
         const docMetadata = docsById[docId];
         if (!docMetadata) {
             throw new Error(`Invalid sidebars file. The document with id "${docId}" was used in the sidebar, but no document with this id could be found.
 Available document ids are:
 - ${Object.keys(docsById).sort().join('\n- ')}`);
         }
+        return docMetadata;
+    }
+    const convertDocLink = (item) => {
+        const docMetadata = getDocById(item.id);
         const { title, permalink, frontMatter: { sidebar_label: sidebarLabel }, } = docMetadata;
         return {
             type: 'link',
             label: sidebarLabel || item.label || title,
             href: permalink,
+            className: item.className,
             customProps: item.customProps,
+            docId: docMetadata.unversionedId,
         };
     };
-    const normalizeItem = (item) => {
+    function getCategoryLinkHref(link) {
+        switch (link === null || link === void 0 ? void 0 : link.type) {
+            case 'doc':
+                return getDocById(link.id).permalink;
+            case 'generated-index':
+                return link.permalink;
+            default:
+                return undefined;
+        }
+    }
+    function convertCategory(item) {
+        const { link, ...rest } = item;
+        const href = getCategoryLinkHref(link);
+        return { ...rest, items: item.items.map(normalizeItem), ...(href && { href }) };
+    }
+    function normalizeItem(item) {
         switch (item.type) {
             case 'category':
-                return { ...item, items: item.items.map(normalizeItem) };
+                return convertCategory(item);
             case 'ref':
             case 'doc':
                 return convertDocLink(item);
@@ -37,21 +58,52 @@ Available document ids are:
             default:
                 return item;
         }
-    };
+    }
     // Transform the sidebar so that all sidebar item will be in the
     // form of 'link' or 'category' only.
     // This is what will be passed as props to the UI component.
-    return lodash_1.mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
+    return (0, lodash_1.mapValues)(loadedVersion.sidebars, (items) => items.map(normalizeItem));
 }
 exports.toSidebarsProp = toSidebarsProp;
+function toVersionDocsProp(loadedVersion) {
+    return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(loadedVersion.docs, (doc) => doc.unversionedId), (doc) => ({
+        id: doc.unversionedId,
+        title: doc.title,
+        description: doc.description,
+        sidebar: doc.sidebar,
+    }));
+}
 function toVersionMetadataProp(pluginId, loadedVersion) {
     return {
         pluginId,
         version: loadedVersion.versionName,
         label: loadedVersion.versionLabel,
         banner: loadedVersion.versionBanner,
+        badge: loadedVersion.versionBadge,
+        className: loadedVersion.versionClassName,
         isLast: loadedVersion.isLast,
         docsSidebars: toSidebarsProp(loadedVersion),
+        docs: toVersionDocsProp(loadedVersion),
     };
 }
 exports.toVersionMetadataProp = toVersionMetadataProp;
+function toTagDocListProp({ allTagsPath, tag, docs, }) {
+    function toDocListProp() {
+        const list = (0, lodash_1.compact)(tag.docIds.map((id) => docs.find((doc) => doc.id === id)));
+        // Sort docs by title
+        list.sort((doc1, doc2) => doc1.title.localeCompare(doc2.title));
+        return list.map((doc) => ({
+            id: doc.id,
+            title: doc.title,
+            description: doc.description,
+            permalink: doc.permalink,
+        }));
+    }
+    return {
+        name: tag.name,
+        permalink: tag.permalink,
+        docs: toDocListProp(),
+        allTagsPath,
+    };
+}
+exports.toTagDocListProp = toTagDocListProp;

package/lib/routes.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
+import { DocMetadata, LoadedVersion } from './types';
+export declare function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, }: {
+    version: LoadedVersion;
+    actions: PluginContentLoadedActions;
+    docCategoryGeneratedIndexComponent: string;
+}): Promise<RouteConfig[]>;
+export declare function createDocRoutes({ docs, actions, docItemComponent, }: {
+    docs: DocMetadata[];
+    actions: PluginContentLoadedActions;
+    docItemComponent: string;
+}): Promise<RouteConfig[]>;
+export declare function createVersionRoutes({ loadedVersion, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }: {
+    loadedVersion: LoadedVersion;
+    actions: PluginContentLoadedActions;
+    docLayoutComponent: string;
+    docItemComponent: string;
+    docCategoryGeneratedIndexComponent: string;
+    pluginId: string;
+    aliasedSource: (str: string) => string;
+}): Promise<void>;

package/lib/routes.js

@@ -0,0 +1,105 @@
+"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.createVersionRoutes = exports.createDocRoutes = exports.createCategoryGeneratedIndexRoutes = void 0;
+const tslib_1 = require("tslib");
+const utils_1 = require("@docusaurus/utils");
+const props_1 = require("./props");
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, }) {
+    const slugs = (0, utils_1.createSlugger)();
+    async function createCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
+        const { sidebar, title, description, slug, permalink, previous, next } = categoryGeneratedIndex;
+        const propFileName = slugs.slug(`${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
+        const prop = {
+            title,
+            description,
+            slug,
+            permalink,
+            navigation: {
+                previous,
+                next,
+            },
+        };
+        const propData = await actions.createData(`${(0, utils_1.docuHash)(`category/${propFileName}`)}.json`, JSON.stringify(prop, null, 2));
+        return {
+            path: permalink,
+            component: docCategoryGeneratedIndexComponent,
+            exact: true,
+            modules: {
+                categoryGeneratedIndex: propData,
+            },
+            // Same as doc, this sidebar route attribute permits to associate this subpage to the given sidebar
+            ...(sidebar && { sidebar }),
+        };
+    }
+    return Promise.all(version.categoryGeneratedIndices.map(createCategoryGeneratedIndexRoute));
+}
+exports.createCategoryGeneratedIndexRoutes = createCategoryGeneratedIndexRoutes;
+async function createDocRoutes({ docs, actions, docItemComponent, }) {
+    return Promise.all(docs.map(async (metadataItem) => {
+        await actions.createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${(0, utils_1.docuHash)(metadataItem.source)}.json`, JSON.stringify(metadataItem, null, 2));
+        const docRoute = {
+            path: metadataItem.permalink,
+            component: docItemComponent,
+            exact: true,
+            modules: {
+                content: metadataItem.source,
+            },
+            // Because the parent (DocPage) comp need to access it easily
+            // This permits to render the sidebar once without unmount/remount when navigating (and preserve sidebar state)
+            ...(metadataItem.sidebar && {
+                sidebar: metadataItem.sidebar,
+            }),
+        };
+        return docRoute;
+    }));
+}
+exports.createDocRoutes = createDocRoutes;
+async function createVersionRoutes({ loadedVersion, actions, docItemComponent, docLayoutComponent, docCategoryGeneratedIndexComponent, pluginId, aliasedSource, }) {
+    async function doCreateVersionRoutes(version) {
+        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() {
+            const [docRoutes, sidebarsRoutes] = await Promise.all([
+                createDocRoutes({ docs: version.docs, actions, docItemComponent }),
+                createCategoryGeneratedIndexRoutes({
+                    version,
+                    actions,
+                    docCategoryGeneratedIndexComponent,
+                }),
+            ]);
+            const routes = [...docRoutes, ...sidebarsRoutes];
+            return routes.sort((a, b) => a.path.localeCompare(b.path));
+        }
+        actions.addRoute({
+            path: version.versionPath,
+            // allow matching /docs/* as well
+            exact: false,
+            // main docs component (DocPage)
+            component: docLayoutComponent,
+            // sub-routes for each doc
+            routes: await createVersionSubRoutes(),
+            modules: {
+                versionMetadata: aliasedSource(versionMetadataPropPath),
+            },
+            priority: version.routePriority,
+        });
+    }
+    try {
+        return await doCreateVersionRoutes(loadedVersion);
+    }
+    catch (e) {
+        console.error(chalk_1.default.red(`Can't create version routes for version "${loadedVersion.versionName}"`));
+        throw e;
+    }
+}
+exports.createVersionRoutes = createVersionRoutes;

package/lib/{sidebarItemsGenerator.d.ts → sidebars/generator.d.ts}

@@ -4,12 +4,15 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { SidebarItemsGenerator } from './types';
+import type { SidebarItemsGenerator, SidebarItemCategoryLinkConfig } from './types';
 export declare const CategoryMetadataFilenameBase = "_category_";
 export declare const CategoryMetadataFilenamePattern = "_category_.{json,yml,yaml}";
-export declare type CategoryMetadatasFile = {
+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

@@ -0,0 +1,216 @@
+"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.DefaultSidebarItemsGenerator = exports.CategoryMetadataFilenamePattern = exports.CategoryMetadataFilenameBase = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = require("lodash");
+const utils_1 = require("@docusaurus/utils");
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+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('/'));
+}
+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) {
+            console.error(chalk_1.default.red(`The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`));
+            throw e;
+        }
+    }
+    // eslint-disable-next-line no-restricted-syntax
+    for (const ext of ['.json', '.yml', '.yaml']) {
+        // Simpler to use only posix paths for mocking file metadata in tests
+        const filePath = (0, utils_1.posixPath)(path_1.default.join(categoryDirPath, `${exports.CategoryMetadataFilenameBase}${ext}`));
+        if (await fs_extra_1.default.pathExists(filePath)) {
+            return tryReadFile(filePath);
+        }
+    }
+    return null;
+}
+// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+    const docsById = (0, docs_1.createDocsByIdIndex)(allDocs);
+    const findDoc = (docId) => docsById[docId];
+    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- ')}`);
+        }
+        return doc;
+    };
+    /**
+     * Step 1. Extract the docs that are in the autogen dir.
+     */
+    function getAutogenDocs() {
+        function isInAutogeneratedDir(doc) {
+            return (
+            // Doc at the root of the autogenerated sidebar dir
+            doc.sourceDirName === autogenDir ||
+                // autogen dir is . and doc is in subfolder
+                autogenDir === '.' ||
+                // 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)));
+        }
+        const docs = allDocs.filter(isInAutogeneratedDir);
+        if (docs.length === 0) {
+            console.warn(chalk_1.default.yellow(`No docs found in dir ${autogenDir}: can't auto-generate a sidebar.`));
+        }
+        return docs;
+    }
+    /**
+     * 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)
+        // 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()
+        function getRelativeBreadcrumb(doc) {
+            return autogenDir === doc.sourceDirName
+                ? []
+                : doc.sourceDirName
+                    .replace((0, utils_1.addTrailingSlash)(autogenDir), '')
+                    .split(BreadcrumbSeparator);
+        }
+        const treeRoot = {};
+        docs.forEach((doc) => {
+            const breadcrumb = getRelativeBreadcrumb(doc);
+            let currentDir = treeRoot; // We walk down the file's path to generate the fs structure
+            // eslint-disable-next-line no-restricted-syntax
+            for (const dir of breadcrumb) {
+                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.
+        });
+        return treeRoot;
+    }
+    /**
+     * Step 3. Recursively transform the tree-like file structure to sidebar items.
+     * (From a record to an array of items, akin to normalizing shorthand)
+     */
+    function generateSidebar(fsModel) {
+        function createDocItem(id) {
+            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = getDoc(id);
+            return {
+                type: 'doc',
+                id,
+                position,
+                // 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);
+            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}`)));
+            // Try to match a doc inside the category folder,
+            // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
+            function findDocByLocalId(localId) {
+                return allItems.find((item) => item.type === 'doc' && getLocalDocId(item.id) === localId);
+            }
+            function findConventionalCategoryDocLink() {
+                return allItems.find((item) => item.type === 'doc' && (0, docs_1.isConventionalDocIndex)(getDoc(item.id)));
+            }
+            function getCategoryLinkedDocId() {
+                var _a, _b;
+                const link = categoryMetadata === null || categoryMetadata === void 0 ? void 0 : categoryMetadata.link;
+                if (link) {
+                    if (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;
+                    }
+                }
+                // 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();
+            const link = categoryLinkedDocId
+                ? {
+                    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;
+            // 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,
+                ...(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`.
+        fullPath) {
+            return dir
+                ? createCategoryItem(dir, fullPath, itemKey)
+                : createDocItem(itemKey.substring(docIdPrefix.length));
+        }
+        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)
+     */
+    function sortItems(sidebarItems) {
+        const processedSidebarItems = sidebarItems.map((item) => {
+            if (item.type === 'category') {
+                return { ...item, items: sortItems(item.items) };
+            }
+            return item;
+        });
+        const sortedSidebarItems = (0, lodash_1.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);
+    const sortedSidebar = sortItems(sidebarWithPosition);
+    return sortedSidebar;
+};
+exports.DefaultSidebarItemsGenerator = DefaultSidebarItemsGenerator;

package/lib/sidebars/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { SidebarsConfig, Sidebars, NormalizedSidebars } from './types';
+import type { NormalizeSidebarsParams, PluginOptions } from '../types';
+import { SidebarProcessorParams } from './processor';
+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 loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -0,0 +1,73 @@
+"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.loadSidebars = exports.loadNormalizedSidebars = exports.loadSidebarsFile = 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 path_1 = (0, tslib_1.__importDefault)(require("path"));
+const utils_1 = require("@docusaurus/utils");
+exports.DefaultSidebars = {
+    defaultSidebar: [
+        {
+            type: 'autogenerated',
+            dirName: '.',
+        },
+    ],
+};
+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)
+        : sidebarPathOption;
+}
+exports.resolveSidebarPathOption = resolveSidebarPathOption;
+function loadSidebarsFileUnsafe(sidebarFilePath) {
+    // false => no sidebars
+    if (sidebarFilePath === false) {
+        return exports.DisabledSidebars;
+    }
+    // undefined => defaults to autogenerated sidebars
+    if (typeof sidebarFilePath === 'undefined') {
+        return exports.DefaultSidebars;
+    }
+    // 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)) {
+        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;
+// 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);
+}
+exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { 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;

package/lib/sidebars/normalization.js

@@ -0,0 +1,77 @@
+"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.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) {
+    return Object.entries(sidebar).map(([label, items]) => ({
+        type: 'category',
+        collapsed: options.sidebarCollapsed,
+        collapsible: options.sidebarCollapsible,
+        label,
+        items,
+    }));
+}
+/**
+ * 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;
+    if (typeof item === 'string') {
+        return [
+            {
+                type: 'doc',
+                id: item,
+            },
+        ];
+    }
+    if ((0, utils_1.isCategoriesShorthand)(item)) {
+        return normalizeCategoriesShorthand(item, options).flatMap((subItem) => normalizeItem(subItem, options));
+    }
+    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,
+        };
+        return [normalizedCategory];
+    }
+    return [item];
+}
+exports.normalizeItem = normalizeItem;
+function normalizeSidebar(sidebar, options) {
+    const normalizedSidebar = Array.isArray(sidebar)
+        ? sidebar
+        : normalizeCategoriesShorthand(sidebar, options);
+    return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem, options));
+}
+function normalizeSidebars(sidebars, params) {
+    return (0, lodash_1.mapValues)(sidebars, (items) => normalizeSidebar(items, params));
+}
+exports.normalizeSidebars = normalizeSidebars;