@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/lib/routes.js

@@ -0,0 +1,184 @@
+"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.buildAllRoutes = buildAllRoutes;
+exports.createAllRoutes = createAllRoutes;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const props_1 = require("./props");
+function createDocRouteMetadata(docMeta) {
+    return {
+        sourceFilePath: (0, utils_1.aliasedSitePathToRelativePath)(docMeta.source),
+        lastUpdatedAt: docMeta.lastUpdatedAt,
+    };
+}
+async function buildVersionCategoryGeneratedIndexRoutes({ version, options, }) {
+    async function buildCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
+        return {
+            path: categoryGeneratedIndex.permalink,
+            component: options.docCategoryGeneratedIndexComponent,
+            exact: true,
+            props: {
+                categoryGeneratedIndex,
+            },
+            // Same as doc, this sidebar route attribute permits to associate this
+            // subpage to the given sidebar
+            ...(categoryGeneratedIndex.sidebar && {
+                sidebar: categoryGeneratedIndex.sidebar,
+            }),
+        };
+    }
+    return Promise.all(version.categoryGeneratedIndices.map(buildCategoryGeneratedIndexRoute));
+}
+async function buildVersionDocRoutes({ version, actions, options, }) {
+    return Promise.all(version.docs.map(async (doc) => {
+        await actions.createData(
+        // Note that this created data path must be in sync with
+        // metadataPath provided to mdx-loader.
+        `${(0, utils_1.docuHash)(doc.source)}.json`, doc);
+        const docRoute = {
+            path: doc.permalink,
+            component: options.docItemComponent,
+            exact: true,
+            modules: {
+                content: doc.source,
+            },
+            metadata: createDocRouteMetadata(doc),
+            // Because the parent (DocRoot) comp need to access it easily
+            // This permits to render the sidebar once without unmount/remount when
+            // navigating (and preserve sidebar state)
+            ...(doc.sidebar && {
+                sidebar: doc.sidebar,
+            }),
+        };
+        return docRoute;
+    }));
+}
+async function buildVersionSidebarRoute(param) {
+    const [docRoutes, categoryGeneratedIndexRoutes] = await Promise.all([
+        buildVersionDocRoutes(param),
+        buildVersionCategoryGeneratedIndexRoutes(param),
+    ]);
+    const subRoutes = [...docRoutes, ...categoryGeneratedIndexRoutes];
+    return {
+        path: param.version.path,
+        exact: false,
+        component: param.options.docRootComponent,
+        routes: subRoutes,
+    };
+}
+function getVersionTags(docs) {
+    const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagDocs }) => {
+        const tagVisibility = (0, utils_1.getTagVisibility)({
+            items: tagDocs,
+            isUnlisted: (item) => item.unlisted,
+        });
+        return {
+            inline: tag.inline,
+            label: tag.label,
+            permalink: tag.permalink,
+            description: tag.description,
+            docIds: tagVisibility.listedItems.map((item) => item.id),
+            unlisted: tagVisibility.unlisted,
+        };
+    });
+}
+async function buildVersionTagsRoutes(param) {
+    const { version, options } = param;
+    const versionTags = getVersionTags(version.docs);
+    async function buildTagsListRoute() {
+        const tags = (0, props_1.toTagsListTagsProp)(versionTags);
+        // Don't create a tags list page if there's no tag
+        if (tags.length === 0) {
+            return null;
+        }
+        return {
+            path: version.tagsPath,
+            exact: true,
+            component: options.docTagsListComponent,
+            props: {
+                tags,
+            },
+        };
+    }
+    async function buildTagDocListRoute(tag) {
+        return {
+            path: tag.permalink,
+            component: options.docTagDocListComponent,
+            exact: true,
+            props: {
+                tag: (0, props_1.toTagDocListProp)({
+                    allTagsPath: version.tagsPath,
+                    tag,
+                    docs: version.docs,
+                }),
+            },
+        };
+    }
+    const [tagsListRoute, allTagsDocListRoutes] = await Promise.all([
+        buildTagsListRoute(),
+        Promise.all(Object.values(versionTags).map(buildTagDocListRoute)),
+    ]);
+    return lodash_1.default.compact([tagsListRoute, ...allTagsDocListRoutes]);
+}
+async function buildVersionRoutes(param) {
+    const { version, options } = param;
+    async function buildVersionSubRoutes() {
+        const [sidebarRoute, tagsRoutes] = await Promise.all([
+            buildVersionSidebarRoute(param),
+            buildVersionTagsRoutes(param),
+        ]);
+        return [sidebarRoute, ...tagsRoutes];
+    }
+    async function doBuildVersionRoutes() {
+        return {
+            path: version.path,
+            exact: false,
+            component: options.docVersionRootComponent,
+            routes: await buildVersionSubRoutes(),
+            props: {
+                // TODO Docusaurus v4 breaking change?
+                //  expose version metadata as route context instead of props
+                version: (0, props_1.toVersionMetadataProp)(options.id, version),
+            },
+            priority: version.routePriority,
+        };
+    }
+    try {
+        return await doBuildVersionRoutes();
+    }
+    catch (err) {
+        logger_1.default.error `Can't create version routes for version name=${version.versionName}`;
+        throw err;
+    }
+}
+// TODO we want this buildAllRoutes function to be easily testable
+// Ideally, we should avoid side effects here (ie not injecting actions)
+async function buildAllRoutes(param) {
+    const subRoutes = await Promise.all(param.versions.map((version) => buildVersionRoutes({
+        ...param,
+        version,
+    })));
+    // all docs routes are wrapped under a single parent route, this ensures
+    // the theme layout never unmounts/remounts when navigating between versions
+    return [
+        {
+            path: (0, utils_1.normalizeUrl)([param.baseUrl, param.options.routeBasePath]),
+            exact: false,
+            component: param.options.docsRootComponent,
+            routes: subRoutes,
+        },
+    ];
+}
+async function createAllRoutes(param) {
+    const routes = await buildAllRoutes(param);
+    routes.forEach(param.actions.addRoute);
+}

package/lib/server-export.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export { CURRENT_VERSION_NAME, VERSIONED_DOCS_DIR, VERSIONED_SIDEBARS_DIR, VERSIONS_JSON_FILE, } from './constants';
+export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, } from './versions/version';
+export { readVersionNames } from './versions/files';

package/lib/server-export.js

@@ -0,0 +1,25 @@
+"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.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
+// Those are undocumented but used by some third-party plugins
+// For this reason it's preferable to avoid doing breaking changes
+// See also https://github.com/facebook/docusaurus/pull/6477
+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 version_1 = require("./versions/version");
+Object.defineProperty(exports, "filterVersions", { enumerable: true, get: function () { return version_1.filterVersions; } });
+Object.defineProperty(exports, "getDefaultVersionBanner", { enumerable: true, get: function () { return version_1.getDefaultVersionBanner; } });
+Object.defineProperty(exports, "getVersionBadge", { enumerable: true, get: function () { return version_1.getVersionBadge; } });
+Object.defineProperty(exports, "getVersionBanner", { enumerable: true, get: function () { return version_1.getVersionBanner; } });
+var files_1 = require("./versions/files");
+Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return files_1.readVersionNames; } });

package/lib/sidebars/generator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 { SidebarItemsGenerator } from './types';
+export declare const CategoryMetadataFilenameBase = "_category_";
+export declare const CategoryMetadataFilenamePattern = "_category_.{json,yml,yaml}";
+export declare const DefaultSidebarItemsGenerator: SidebarItemsGenerator;

package/lib/sidebars/generator.js

@@ -0,0 +1,217 @@
+"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 node_path_1 = tslib_1.__importDefault(require("node:path"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_common_1 = require("@docusaurus/utils-common");
+const docs_1 = require("../docs");
+const BreadcrumbSeparator = '/';
+// Just an alias to the make code more explicit
+function getLocalDocId(docId) {
+    return lodash_1.default.last(docId.split('/'));
+}
+exports.CategoryMetadataFilenameBase = '_category_';
+exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
+// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+const DefaultSidebarItemsGenerator = ({ numberPrefixParser, isCategoryIndex, docs: allDocs, item: { dirName: autogenDir }, categoriesMetadata, }) => {
+    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}.
+Available doc IDs:
+- ${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_common_1.addTrailingSlash)(autogenDir)));
+        }
+        const docs = allDocs.filter(isInAutogeneratedDir);
+        if (docs.length === 0) {
+            logger_1.default.warn `No docs found in path=${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_common_1.addTrailingSlash)(autogenDir), '')
+                    .split(BreadcrumbSeparator);
+        }
+        const treeRoot = {};
+        docs.forEach((doc) => {
+            const breadcrumb = getRelativeBreadcrumb(doc);
+            // We walk down the file's path to generate the fs structure
+            let currentDir = treeRoot;
+            breadcrumb.forEach((dir) => {
+                if (typeof currentDir[dir] === 'undefined') {
+                    currentDir[dir] = {}; // Create new folder.
+                }
+                currentDir = currentDir[dir]; // Go into the subdirectory.
+            });
+            // We've walked through the path. Register the file in this directory.
+            currentDir[node_path_1.default.basename(doc.source)] = doc.id;
+        });
+        return treeRoot;
+    }
+    /**
+     * 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) {
+        function createDocItem(id, fullPath, fileName) {
+            const { sidebarPosition: position, frontMatter: { sidebar_key: key, sidebar_label: label, sidebar_class_name: className, sidebar_custom_props: customProps, }, } = getDoc(id);
+            return {
+                type: 'doc',
+                id,
+                position,
+                source: fileName,
+                // We don't want these fields to magically appear in the generated
+                // sidebar
+                ...(key !== undefined && { key }),
+                ...(label !== undefined && { label }),
+                ...(className !== undefined && { className }),
+                ...(customProps !== undefined && { customProps }),
+            };
+        }
+        function createCategoryItem(dir, fullPath, folderName) {
+            const categoryMetadata = categoriesMetadata[node_path_1.default.posix.join(autogenDir, fullPath)];
+            const allItems = Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`));
+            // Try to match a doc inside the category folder,
+            // using the "local id" (myDoc) or "qualified id" (dirName/myDoc)
+            function findDocByLocalId(localId) {
+                return allItems.find((item) => item.type === 'doc' && getLocalDocId(item.id) === localId);
+            }
+            function findConventionalCategoryDocLink() {
+                return allItems.find((item) => {
+                    if (item.type !== 'doc') {
+                        return false;
+                    }
+                    const doc = getDoc(item.id);
+                    return isCategoryIndex((0, docs_1.toCategoryIndexMatcherParam)(doc));
+                });
+            }
+            // In addition to the ID, this function also retrieves metadata of the
+            // linked doc that could be used as fallback values for category metadata
+            function getCategoryLinkedDocMetadata() {
+                const link = categoryMetadata?.link;
+                if (link !== undefined && link?.type !== 'doc') {
+                    // If a link is explicitly specified, we won't apply conventions
+                    return undefined;
+                }
+                const id = link
+                    ? (findDocByLocalId(link.id)?.id ?? getDoc(link.id).id)
+                    : findConventionalCategoryDocLink()?.id;
+                if (!id) {
+                    return undefined;
+                }
+                const doc = getDoc(id);
+                return {
+                    id,
+                    position: doc.sidebarPosition,
+                    key: doc.frontMatter.sidebar_key,
+                    label: doc.frontMatter.sidebar_label ?? doc.title,
+                    customProps: doc.frontMatter.sidebar_custom_props,
+                    className: doc.frontMatter.sidebar_class_name,
+                };
+            }
+            const categoryLinkedDoc = getCategoryLinkedDocMetadata();
+            const link = categoryLinkedDoc
+                ? {
+                    type: 'doc',
+                    id: categoryLinkedDoc.id, // We "remap" a potentially "local id" to a "qualified id"
+                }
+                : categoryMetadata?.link;
+            // If a doc is linked, remove it from the category subItems
+            const items = allItems.filter((item) => !(item.type === 'doc' && item.id === categoryLinkedDoc?.id));
+            const className = categoryMetadata?.className ?? categoryLinkedDoc?.className;
+            const customProps = categoryMetadata?.customProps ?? categoryLinkedDoc?.customProps;
+            const { filename, numberPrefix } = numberPrefixParser(folderName);
+            const key = categoryMetadata?.key ?? categoryLinkedDoc?.key;
+            return {
+                type: 'category',
+                label: categoryMetadata?.label ?? categoryLinkedDoc?.label ?? filename,
+                collapsible: categoryMetadata?.collapsible,
+                collapsed: categoryMetadata?.collapsed,
+                position: categoryMetadata?.position ??
+                    categoryLinkedDoc?.position ??
+                    numberPrefix,
+                source: folderName,
+                ...(customProps !== undefined && { customProps }),
+                ...(className !== undefined && { className }),
+                items,
+                ...(categoryMetadata?.description && {
+                    description: categoryMetadata?.description,
+                }),
+                ...(key && { key }),
+                ...(link && { link }),
+            };
+        }
+        function dirToItem(dir, // The directory item to be transformed.
+        itemKey, // File/folder name; for categories, it's used to generate the next `relativePath`.
+        fullPath) {
+            return typeof dir === 'object'
+                ? createCategoryItem(dir, fullPath, itemKey)
+                : createDocItem(dir, fullPath, itemKey);
+        }
+        return 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 (i.e. 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 = lodash_1.default.sortBy(processedSidebarItems, [
+            'position',
+            'source',
+        ]);
+        return sortedSidebarItems.map(({ position, source, ...item }) => item);
+    }
+    // TODO: the whole code is designed for pipeline operator
+    const docs = getAutogenDocs();
+    const fsModel = treeify(docs);
+    const sidebarWithPosition = generateSidebar(fsModel);
+    const sortedSidebar = sortItems(sidebarWithPosition);
+    return sortedSidebar;
+};
+exports.DefaultSidebarItemsGenerator = DefaultSidebarItemsGenerator;

package/lib/sidebars/index.d.ts

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

package/lib/sidebars/index.js

@@ -0,0 +1,99 @@
+"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.DisabledSidebars = exports.DefaultSidebars = void 0;
+exports.resolveSidebarPathOption = resolveSidebarPathOption;
+exports.loadSidebarsFile = loadSidebarsFile;
+exports.loadSidebars = loadSidebars;
+const tslib_1 = require("tslib");
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const glob_1 = require("@docusaurus/glob");
+const Yaml = tslib_1.__importStar(require("js-yaml"));
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+const fs_1 = require("@docusaurus/fs");
+const validation_1 = require("./validation");
+const normalization_1 = require("./normalization");
+const processor_1 = require("./processor");
+const postProcessor_1 = require("./postProcessor");
+exports.DefaultSidebars = {
+    defaultSidebar: [
+        {
+            type: 'autogenerated',
+            dirName: '.',
+        },
+    ],
+};
+exports.DisabledSidebars = {};
+// If a path is provided, make it absolute
+function resolveSidebarPathOption(siteDir, sidebarPathOption) {
+    return sidebarPathOption
+        ? node_path_1.default.resolve(siteDir, sidebarPathOption)
+        : sidebarPathOption;
+}
+async function readCategoriesMetadata(contentPath) {
+    const categoryFiles = await (0, glob_1.glob)('**/_category_.{json,yml,yaml}', {
+        cwd: contentPath,
+    });
+    const categoryToFile = lodash_1.default.groupBy(categoryFiles, node_path_1.default.dirname);
+    return (0, combine_promises_1.default)(lodash_1.default.mapValues(categoryToFile, async (files, folder) => {
+        const filePath = files[0];
+        if (files.length > 1) {
+            logger_1.default.warn `There are more than one category metadata files for path=${folder}: ${files.join(', ')}. The behavior is undetermined.`;
+        }
+        const content = await fs_1.fs.readFile(node_path_1.default.join(contentPath, filePath), 'utf-8');
+        try {
+            return (0, validation_1.validateCategoryMetadataFile)(Yaml.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;
+    }
+    // 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 (!(await (0, fs_1.pathExists)(sidebarFilePath))) {
+        return exports.DisabledSidebars;
+    }
+    // We don't want sidebars to be cached because of hot reloading.
+    const module = await (0, utils_1.loadFreshModule)(sidebarFilePath, { default: true });
+    // TODO unsafe, need to refactor and improve validation
+    return module;
+}
+async function loadSidebarsFile(sidebarFilePath) {
+    const sidebars = await loadSidebarsFileUnsafe(sidebarFilePath);
+    // TODO unsafe, need to refactor and improve validation
+    return sidebars;
+}
+async function loadSidebars(sidebarFilePath, options) {
+    try {
+        const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
+        const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig);
+        (0, validation_1.validateSidebars)(normalizedSidebars);
+        const categoriesMetadata = await readCategoriesMetadata(options.version.contentPath);
+        const processedSidebars = await (0, processor_1.processSidebars)(normalizedSidebars, categoriesMetadata, options);
+        return (0, postProcessor_1.postProcessSidebars)(processedSidebars, options);
+    }
+    catch (err) {
+        logger_1.default.error `Sidebars file at path=${sidebarFilePath} failed to be loaded.`;
+        throw err;
+    }
+}

package/lib/sidebars/normalization.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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 { 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): NormalizedSidebarItem[];
+export declare function normalizeSidebars(sidebars: SidebarsConfig): NormalizedSidebars;

package/lib/sidebars/normalization.js

@@ -0,0 +1,58 @@
+"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.normalizeItem = normalizeItem;
+exports.normalizeSidebars = normalizeSidebars;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("./utils");
+function normalizeCategoriesShorthand(sidebar) {
+    return Object.entries(sidebar).map(([label, items]) => ({
+        type: 'category',
+        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) {
+    if (typeof item === 'string') {
+        return [{ type: 'doc', id: item }];
+    }
+    if ((0, utils_1.isCategoriesShorthand)(item)) {
+        // This will never throw anyways
+        return normalizeSidebar(item, 'sidebar items slice');
+    }
+    if ((item.type === 'doc' || item.type === 'ref') &&
+        typeof item.label === 'string') {
+        return [{ ...item, translatable: true }];
+    }
+    if (item.type === 'category') {
+        const normalizedCategory = {
+            ...item,
+            items: normalizeSidebar(item.items, logger_1.default.interpolate `code=${'items'} of the category name=${item.label}`),
+        };
+        return [normalizedCategory];
+    }
+    return [item];
+}
+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 url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`);
+    }
+    const normalizedSidebar = Array.isArray(sidebar)
+        ? sidebar
+        : normalizeCategoriesShorthand(sidebar);
+    return normalizedSidebar.flatMap((subItem) => normalizeItem(subItem));
+}
+function normalizeSidebars(sidebars) {
+    return lodash_1.default.mapValues(sidebars, (sidebar, id) => normalizeSidebar(sidebar, logger_1.default.interpolate `sidebar name=${id}`));
+}

package/lib/sidebars/postProcessor.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 type SidebarPostProcessorParams = SidebarProcessorParams & {
+    draftIds: Set<string>;
+};
+export declare function postProcessSidebars(sidebars: ProcessedSidebars, params: SidebarProcessorParams): Sidebars;