@docusaurus/plugin-content-docs 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/lib/options.js

@@ -3,19 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateOptions = exports.OptionsSchema = exports.DEFAULT_OPTIONS = void 0;
 const tslib_1 = require("tslib");
 const utils_validation_1 = require("@docusaurus/utils-validation");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
-const remark_admonitions_1 = tslib_1.__importDefault(require("remark-admonitions"));
-const sidebarItemsGenerator_1 = require("./sidebarItemsGenerator");
+const utils_1 = require("@docusaurus/utils");
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const remark_admonitions_1 = (0, tslib_1.__importDefault)(require("remark-admonitions"));
+const generator_1 = require("./sidebars/generator");
 const numberPrefix_1 = require("./numberPrefix");
 exports.DEFAULT_OPTIONS = {
     path: 'docs',
     routeBasePath: 'docs',
+    tagsBasePath: 'tags',
     homePageId: undefined,
     include: ['**/*.{md,mdx}'],
-    sidebarItemsGenerator: sidebarItemsGenerator_1.DefaultSidebarItemsGenerator,
+    exclude: utils_1.GlobExcludeDefault,
+    sidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
     numberPrefixParser: numberPrefix_1.DefaultNumberPrefixParser,
     docLayoutComponent: '@theme/DocPage',
     docItemComponent: '@theme/DocItem',
+    docTagDocListComponent: '@theme/DocTagDocListPage',
+    docTagsListComponent: '@theme/DocTagsListPage',
     remarkPlugins: [],
     rehypePlugins: [],
     beforeDefaultRemarkPlugins: [],
@@ -23,17 +28,21 @@ exports.DEFAULT_OPTIONS = {
     showLastUpdateTime: false,
     showLastUpdateAuthor: false,
     admonitions: {},
-    excludeNextVersionDocs: false,
     includeCurrentVersion: true,
     disableVersioning: false,
     lastVersion: undefined,
     versions: {},
     editCurrentVersion: false,
     editLocalizedFiles: false,
+    sidebarCollapsible: true,
+    sidebarCollapsed: true,
 };
 const VersionOptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().allow('').optional(),
     label: utils_validation_1.Joi.string().optional(),
+    banner: utils_validation_1.Joi.string().equal('none', 'unreleased', 'unmaintained').optional(),
+    badge: utils_validation_1.Joi.boolean().optional(),
+    className: utils_validation_1.Joi.string().optional(),
 });
 const VersionsOptionsSchema = utils_validation_1.Joi.object()
     .pattern(utils_validation_1.Joi.string().required(), VersionOptionsSchema)
@@ -47,10 +56,14 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
         // .allow('') ""
         .default(exports.DEFAULT_OPTIONS.routeBasePath),
+    tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
     homePageId: utils_validation_1.Joi.string().optional(),
     include: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.include),
+    exclude: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()).default(exports.DEFAULT_OPTIONS.exclude),
     sidebarPath: utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.boolean().invalid(true), utils_validation_1.Joi.string()),
     sidebarItemsGenerator: utils_validation_1.Joi.function().default(() => exports.DEFAULT_OPTIONS.sidebarItemsGenerator),
+    sidebarCollapsible: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.sidebarCollapsible),
+    sidebarCollapsed: utils_validation_1.Joi.boolean().default(exports.DEFAULT_OPTIONS.sidebarCollapsed),
     numberPrefixParser: utils_validation_1.Joi.alternatives()
         .try(utils_validation_1.Joi.function(), 
     // Convert boolean values to functions
@@ -60,6 +73,8 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         .default(() => exports.DEFAULT_OPTIONS.numberPrefixParser),
     docLayoutComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docLayoutComponent),
     docItemComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docItemComponent),
+    docTagsListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docTagsListComponent),
+    docTagDocListComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docTagDocListComponent),
     remarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.remarkPlugins),
     rehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.rehypePlugins),
     beforeDefaultRemarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRemarkPlugins),
@@ -69,23 +84,36 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         .default(exports.DEFAULT_OPTIONS.admonitions),
     showLastUpdateTime: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateTime),
     showLastUpdateAuthor: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.showLastUpdateAuthor),
-    excludeNextVersionDocs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.excludeNextVersionDocs),
     includeCurrentVersion: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.includeCurrentVersion),
     onlyIncludeVersions: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().required()).optional(),
     disableVersioning: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.disableVersioning),
     lastVersion: utils_validation_1.Joi.string().optional(),
     versions: VersionsOptionsSchema,
 });
-function validateOptions({ validate, options, }) {
+function validateOptions({ validate, options: userOptions, }) {
+    let options = userOptions;
+    if (options.sidebarCollapsible === false) {
+        // When sidebarCollapsible=false and sidebarCollapsed=undefined, we don't want to have the inconsistency warning
+        // We let options.sidebarCollapsible become the default value for options.sidebarCollapsed
+        if (typeof options.sidebarCollapsed === 'undefined') {
+            options = {
+                ...options,
+                sidebarCollapsed: false,
+            };
+        }
+        if (options.sidebarCollapsed) {
+            console.warn(chalk_1.default.yellow('The docs plugin config is inconsistent. It does not make sense to use sidebarCollapsible=false and sidebarCollapsed=true at the same time. sidebarCollapsed=false will be ignored.'));
+            options = {
+                ...options,
+                sidebarCollapsed: false,
+            };
+        }
+    }
     // TODO remove homePageId before end of 2020
     // "slug: /" is better because the home doc can be different across versions
     if (options.homePageId) {
         console.log(chalk_1.default.red(`The docs plugin option homePageId=${options.homePageId} is deprecated. To make a doc the "home", prefer frontmatter: "slug: /"`));
     }
-    if (typeof options.excludeNextVersionDocs !== 'undefined') {
-        console.log(chalk_1.default.red(`The docs plugin option "excludeNextVersionDocs=${options.excludeNextVersionDocs}" is deprecated. Use the "includeCurrentVersion=${!options.excludeNextVersionDocs}" option instead!"`));
-        options.includeCurrentVersion = !options.excludeNextVersionDocs;
-    }
     const normalizedOptions = validate(exports.OptionsSchema, options);
     if (normalizedOptions.admonitions) {
         normalizedOptions.remarkPlugins = normalizedOptions.remarkPlugins.concat([

package/lib/props.d.ts

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

package/lib/props.js

@@ -6,10 +6,10 @@
  * 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");
 function toSidebarsProp(loadedVersion) {
-    const docsById = lodash_1.keyBy(loadedVersion.docs, (doc) => doc.id);
+    const docsById = (0, lodash_1.keyBy)(loadedVersion.docs, (doc) => doc.id);
     const convertDocLink = (item) => {
         const docId = item.id;
         const docMetadata = docsById[docId];
@@ -23,6 +23,7 @@ Available document ids are:
             type: 'link',
             label: sidebarLabel || item.label || title,
             href: permalink,
+            className: item.className,
             customProps: item.customProps,
         };
     };
@@ -41,7 +42,7 @@ Available document ids are:
     // 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 toVersionMetadataProp(pluginId, loadedVersion) {
@@ -49,9 +50,31 @@ function toVersionMetadataProp(pluginId, loadedVersion) {
         pluginId,
         version: loadedVersion.versionName,
         label: loadedVersion.versionLabel,
+        banner: loadedVersion.versionBanner,
+        badge: loadedVersion.versionBadge,
+        className: loadedVersion.versionClassName,
         isLast: loadedVersion.isLast,
         docsSidebars: toSidebarsProp(loadedVersion),
-        permalinkToSidebar: loadedVersion.permalinkToSidebar,
     };
 }
 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/{sidebarItemsGenerator.d.ts → sidebars/generator.d.ts}

@@ -4,12 +4,14 @@
  * 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 } from './types';
 export declare const CategoryMetadataFilenameBase = "_category_";
 export declare const CategoryMetadataFilenamePattern = "_category_.{json,yml,yaml}";
 export declare type CategoryMetadatasFile = {
     label?: string;
     position?: number;
     collapsed?: boolean;
+    collapsible?: boolean;
+    className?: string;
 };
 export declare const DefaultSidebarItemsGenerator: SidebarItemsGenerator;

package/lib/sidebars/generator.js

@@ -0,0 +1,174 @@
+"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 utils_validation_1 = require("@docusaurus/utils-validation");
+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 BreadcrumbSeparator = '/';
+// To avoid possible name clashes with a folder of the same name as the ID
+const docIdPrefix = '$doc$/';
+exports.CategoryMetadataFilenameBase = '_category_';
+exports.CategoryMetadataFilenamePattern = '_category_.{json,yml,yaml}';
+const CategoryMetadatasFileSchema = utils_validation_1.Joi.object({
+    label: utils_validation_1.Joi.string(),
+    position: utils_validation_1.Joi.number(),
+    collapsed: utils_validation_1.Joi.boolean(),
+    collapsible: utils_validation_1.Joi.boolean(),
+    className: utils_validation_1.Joi.string(),
+});
+// 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/index.md`, we may want to read the metadata as yaml on it
+// see https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+async function readCategoryMetadatasFile(categoryDirPath) {
+    var _a, _b;
+    async function tryReadFile(fileNameWithExtension, parse) {
+        // Simpler to use only posix paths for mocking file metadatas in tests
+        const filePath = (0, utils_1.posixPath)(path_1.default.join(categoryDirPath, fileNameWithExtension));
+        if (await fs_extra_1.default.pathExists(filePath)) {
+            const contentString = await fs_extra_1.default.readFile(filePath, { encoding: 'utf8' });
+            const unsafeContent = parse(contentString);
+            try {
+                return utils_validation_1.Joi.attempt(unsafeContent, CategoryMetadatasFileSchema);
+            }
+            catch (e) {
+                console.error(chalk_1.default.red(`The docs sidebar category metadata file looks invalid!\nPath: ${filePath}`));
+                throw e;
+            }
+        }
+        return null;
+    }
+    return ((_b = (_a = (await tryReadFile(`${exports.CategoryMetadataFilenameBase}.json`, JSON.parse))) !== null && _a !== void 0 ? _a : (await tryReadFile(`${exports.CategoryMetadataFilenameBase}.yml`, js_yaml_1.default.load))) !== null && _b !== void 0 ? _b : 
+    // eslint-disable-next-line no-return-await
+    (await tryReadFile(`${exports.CategoryMetadataFilenameBase}.yaml`, js_yaml_1.default.load)));
+}
+// Comment for this feature: https://github.com/facebook/docusaurus/issues/3464#issuecomment-818670449
+const DefaultSidebarItemsGenerator = async ({ numberPrefixParser, docs: allDocs, options, item: { dirName: autogenDir }, version, }) => {
+    /**
+     * 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) {
+        const docsById = (0, lodash_1.keyBy)(allDocs, (doc) => doc.id);
+        function createDocItem(id) {
+            const { sidebarPosition: position, frontMatter: { sidebar_label: label, sidebar_class_name: className }, } = docsById[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 categoryMetadatas = await readCategoryMetadatasFile(categoryPath);
+            const className = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.className;
+            const { filename, numberPrefix } = numberPrefixParser(folderName);
+            return {
+                type: 'category',
+                label: (_a = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.label) !== null && _a !== void 0 ? _a : filename,
+                collapsible: (_b = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.collapsible) !== null && _b !== void 0 ? _b : options.sidebarCollapsible,
+                collapsed: (_c = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.collapsed) !== null && _c !== void 0 ? _c : options.sidebarCollapsed,
+                position: (_d = categoryMetadatas === null || categoryMetadatas === void 0 ? void 0 : categoryMetadatas.position) !== null && _d !== void 0 ? _d : numberPrefix,
+                ...(className !== undefined && { className }),
+                items: await Promise.all(Object.entries(dir).map(([key, content]) => dirToItem(content, key, `${fullPath}/${key}`))),
+            };
+        }
+        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,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 { SidebarsConfig, Sidebars, NormalizedSidebars } from './types';
+import type { PluginOptions } from '../types';
+import { SidebarProcessorProps } 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 loadUnprocessedSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorProps['options']): NormalizedSidebars;
+export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorProps): Promise<Sidebars>;

package/lib/sidebars/index.js

@@ -0,0 +1,64 @@
+"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.loadUnprocessedSidebars = 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"));
+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 loadSidebarFile(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 loadUnprocessedSidebars(sidebarFilePath, options) {
+    const sidebarsConfig = loadSidebarFile(sidebarFilePath);
+    (0, validation_1.validateSidebars)(sidebarsConfig);
+    const normalizedSidebars = (0, normalization_1.normalizeSidebars)(sidebarsConfig, options);
+    return normalizedSidebars;
+}
+exports.loadUnprocessedSidebars = loadUnprocessedSidebars;
+// Note: sidebarFilePath must be absolute, use resolveSidebarPathOption
+async function loadSidebars(sidebarFilePath, options) {
+    const unprocessedSidebars = loadUnprocessedSidebars(sidebarFilePath, options.options);
+    return (0, processor_1.processSidebars)(unprocessedSidebars, options);
+}
+exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.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.
+ */
+import type { SidebarOptions } from '../types';
+import { NormalizedSidebars, SidebarsConfig } from './types';
+export declare function normalizeSidebars(sidebars: SidebarsConfig, options: SidebarOptions): 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.normalizeSidebars = void 0;
+const types_1 = require("./types");
+const lodash_1 = require("lodash");
+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;
+    if (typeof item === 'string') {
+        return [
+            {
+                type: 'doc',
+                id: item,
+            },
+        ];
+    }
+    if ((0, types_1.isCategoriesShorthand)(item)) {
+        return normalizeCategoriesShorthand(item, options).flatMap((subitem) => normalizeItem(subitem, options));
+    }
+    return item.type === 'category'
+        ? [
+            {
+                ...item,
+                items: item.items.flatMap((subItem) => normalizeItem(subItem, options)),
+                collapsible: (_a = item.collapsible) !== null && _a !== void 0 ? _a : options.sidebarCollapsible,
+                collapsed: (_b = item.collapsed) !== null && _b !== void 0 ? _b : options.sidebarCollapsed,
+            },
+        ]
+        : [item];
+}
+function normalizeSidebar(sidebar, options) {
+    const normalizedSidebar = Array.isArray(sidebar)
+        ? sidebar
+        : normalizeCategoriesShorthand(sidebar, options);
+    return normalizedSidebar.flatMap((subitem) => normalizeItem(subitem, options));
+}
+function normalizeSidebars(sidebars, options) {
+    return (0, lodash_1.mapValues)(sidebars, (subitem) => normalizeSidebar(subitem, options));
+}
+exports.normalizeSidebars = normalizeSidebars;

package/lib/sidebars/processor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 { NumberPrefixParser, DocMetadataBase, VersionMetadata, SidebarOptions } from '../types';
+import type { Sidebars, NormalizedSidebars, SidebarItemsGeneratorOption } from './types';
+export declare type SidebarProcessorProps = {
+    sidebarItemsGenerator: SidebarItemsGeneratorOption;
+    numberPrefixParser: NumberPrefixParser;
+    docs: DocMetadataBase[];
+    version: VersionMetadata;
+    options: SidebarOptions;
+};
+export declare function processSidebars(unprocessedSidebars: NormalizedSidebars, props: SidebarProcessorProps): Promise<Sidebars>;

package/lib/sidebars/processor.js

@@ -0,0 +1,70 @@
+"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.processSidebars = void 0;
+const tslib_1 = require("tslib");
+const utils_1 = require("./utils");
+const generator_1 = require("./generator");
+const lodash_1 = require("lodash");
+const combine_promises_1 = (0, tslib_1.__importDefault)(require("combine-promises"));
+function toSidebarItemsGeneratorDoc(doc) {
+    return (0, lodash_1.pick)(doc, [
+        'id',
+        'frontMatter',
+        'source',
+        'sourceDirName',
+        'sidebarPosition',
+    ]);
+}
+function toSidebarItemsGeneratorVersion(version) {
+    return (0, lodash_1.pick)(version, ['versionName', 'contentPath']);
+}
+// Handle the generation of autogenerated sidebar items and other post-processing checks
+async function processSidebar(unprocessedSidebar, { sidebarItemsGenerator, numberPrefixParser, docs, version, options, }) {
+    // Just a minor lazy transformation optimization
+    const getSidebarItemsGeneratorDocsAndVersion = (0, lodash_1.memoize)(() => ({
+        docs: docs.map(toSidebarItemsGeneratorDoc),
+        version: toSidebarItemsGeneratorVersion(version),
+    }));
+    async function handleAutoGeneratedItems(item) {
+        if (item.type === 'category') {
+            return [
+                {
+                    ...item,
+                    items: (await Promise.all(item.items.map(handleAutoGeneratedItems))).flat(),
+                },
+            ];
+        }
+        if (item.type === 'autogenerated') {
+            return sidebarItemsGenerator({
+                item,
+                numberPrefixParser,
+                defaultSidebarItemsGenerator: generator_1.DefaultSidebarItemsGenerator,
+                ...getSidebarItemsGeneratorDocsAndVersion(),
+                options,
+            });
+        }
+        return [item];
+    }
+    const processedSidebar = (await Promise.all(unprocessedSidebar.map(handleAutoGeneratedItems))).flat();
+    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);
+}
+async function processSidebars(unprocessedSidebars, props) {
+    return (0, combine_promises_1.default)((0, lodash_1.mapValues)(unprocessedSidebars, (unprocessedSidebar) => processSidebar(unprocessedSidebar, props)));
+}
+exports.processSidebars = processSidebars;