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

package/lib/options.js

@@ -1,21 +1,32 @@
 "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.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 utils_1 = require("@docusaurus/utils");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const remark_admonitions_1 = tslib_1.__importDefault(require("remark-admonitions"));
-const sidebarItemsGenerator_1 = require("./sidebarItemsGenerator");
+const generator_1 = require("./sidebars/generator");
 const numberPrefix_1 = require("./numberPrefix");
 exports.DEFAULT_OPTIONS = {
     path: 'docs',
     routeBasePath: 'docs',
-    homePageId: undefined,
+    tagsBasePath: 'tags',
     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',
+    docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
     remarkPlugins: [],
     rehypePlugins: [],
     beforeDefaultRemarkPlugins: [],
@@ -29,11 +40,16 @@ exports.DEFAULT_OPTIONS = {
     versions: {},
     editCurrentVersion: false,
     editLocalizedFiles: false,
+    sidebarCollapsible: true,
+    sidebarCollapsed: true,
+    breadcrumbs: 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 +63,16 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
         // '' not allowed, see https://github.com/facebook/docusaurus/issues/3374
         // .allow('') ""
         .default(exports.DEFAULT_OPTIONS.routeBasePath),
-    homePageId: utils_validation_1.Joi.string().optional(),
+    tagsBasePath: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.tagsBasePath),
+    homePageId: utils_validation_1.Joi.any().forbidden().messages({
+        'any.unknown': 'The docs plugin option homePageId is not supported anymore. To make a doc the "home", please add "slug: /" in its front matter. See: https://docusaurus.io/docs/next/docs-introduction#home-page-docs',
+    }),
     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 +82,9 @@ 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),
+    docCategoryGeneratedIndexComponent: utils_validation_1.Joi.string().default(exports.DEFAULT_OPTIONS.docCategoryGeneratedIndexComponent),
     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),
@@ -74,12 +99,27 @@ exports.OptionsSchema = utils_validation_1.Joi.object({
     disableVersioning: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.disableVersioning),
     lastVersion: utils_validation_1.Joi.string().optional(),
     versions: VersionsOptionsSchema,
+    breadcrumbs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.breadcrumbs),
 });
-function validateOptions({ validate, options, }) {
-    // 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: /"`));
+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) {
+            logger_1.default.warn `The docs plugin config is inconsistent. It does not make sense to use code=${'sidebarCollapsible: false'} and code=${'sidebarCollapsed: true'} at the same time. code=${'sidebarCollapsed: true'} will be ignored.`;
+            options = {
+                ...options,
+                sidebarCollapsed: false,
+            };
+        }
     }
     const normalizedOptions = validate(exports.OptionsSchema, options);
     if (normalizedOptions.admonitions) {

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 type { LoadedVersion, VersionTag, DocMetadata } from './types';
+import type { PropSidebars, PropVersionMetadata, PropTagDocList } from '@docusaurus/plugin-content-docs';
 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,30 +6,52 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
-const lodash_1 = require("lodash");
+exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = void 0;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(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,
-            customProps: item.customProps,
+            className: item.className,
+            customProps: item.customProps ?? docMetadata.frontMatter.sidebar_custom_props,
+            docId: docMetadata.unversionedId,
         };
     };
-    const normalizeItem = (item) => {
+    function getCategoryLinkHref(link) {
+        switch (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,22 +59,55 @@ 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 lodash_1.default.mapValues(loadedVersion.sidebars, (items) => items.map(normalizeItem));
 }
 exports.toSidebarsProp = toSidebarsProp;
+function toVersionDocsProp(loadedVersion) {
+    return Object.fromEntries(loadedVersion.docs.map((doc) => [
+        doc.unversionedId,
+        {
+            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),
-        permalinkToSidebar: loadedVersion.permalinkToSidebar,
+        docs: toVersionDocsProp(loadedVersion),
     };
 }
 exports.toVersionMetadataProp = toVersionMetadataProp;
+function toTagDocListProp({ allTagsPath, tag, docs, }) {
+    function toDocListProp() {
+        const list = lodash_1.default.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,28 @@
+/**
+ * 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 { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
+import type { DocMetadata, LoadedVersion } from './types';
+export declare function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }: {
+    version: LoadedVersion;
+    actions: PluginContentLoadedActions;
+    docCategoryGeneratedIndexComponent: string;
+    aliasedSource: (str: string) => 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,110 @@
+"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 logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+async function createCategoryGeneratedIndexRoutes({ version, actions, docCategoryGeneratedIndexComponent, aliasedSource, }) {
+    const slugs = (0, utils_1.createSlugger)();
+    async function createCategoryGeneratedIndexRoute(categoryGeneratedIndex) {
+        const { sidebar, title, description, slug, permalink, previous, next, image, keywords, } = categoryGeneratedIndex;
+        const propFileName = slugs.slug(`${version.versionPath}-${categoryGeneratedIndex.sidebar}-category-${categoryGeneratedIndex.title}`);
+        const prop = {
+            title,
+            description,
+            slug,
+            permalink,
+            image,
+            keywords,
+            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: aliasedSource(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,
+                    aliasedSource,
+                }),
+            ]);
+            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 (err) {
+        logger_1.default.error `Can't create version routes for version name=${loadedVersion.versionName}`;
+        throw err;
+    }
+}
+exports.createVersionRoutes = createVersionRoutes;

package/lib/server-export.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export { CURRENT_VERSION_NAME, VERSIONED_DOCS_DIR, VERSIONED_SIDEBARS_DIR, VERSIONS_JSON_FILE, } from './constants';
+export { filterVersions, getDefaultVersionBanner, getVersionBadge, getVersionBanner, getVersionsFilePath, readVersionsFile, readVersionNames, } from './versions';

package/lib/server-export.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionBanner = exports.getVersionBadge = exports.getDefaultVersionBanner = exports.filterVersions = exports.VERSIONS_JSON_FILE = exports.VERSIONED_SIDEBARS_DIR = exports.VERSIONED_DOCS_DIR = exports.CURRENT_VERSION_NAME = void 0;
+// APIs available to Node.js
+var constants_1 = require("./constants");
+Object.defineProperty(exports, "CURRENT_VERSION_NAME", { enumerable: true, get: function () { return constants_1.CURRENT_VERSION_NAME; } });
+Object.defineProperty(exports, "VERSIONED_DOCS_DIR", { enumerable: true, get: function () { return constants_1.VERSIONED_DOCS_DIR; } });
+Object.defineProperty(exports, "VERSIONED_SIDEBARS_DIR", { enumerable: true, get: function () { return constants_1.VERSIONED_SIDEBARS_DIR; } });
+Object.defineProperty(exports, "VERSIONS_JSON_FILE", { enumerable: true, get: function () { return constants_1.VERSIONS_JSON_FILE; } });
+var versions_1 = require("./versions");
+Object.defineProperty(exports, "filterVersions", { enumerable: true, get: function () { return versions_1.filterVersions; } });
+Object.defineProperty(exports, "getDefaultVersionBanner", { enumerable: true, get: function () { return versions_1.getDefaultVersionBanner; } });
+Object.defineProperty(exports, "getVersionBadge", { enumerable: true, get: function () { return versions_1.getVersionBadge; } });
+Object.defineProperty(exports, "getVersionBanner", { enumerable: true, get: function () { return versions_1.getVersionBanner; } });
+Object.defineProperty(exports, "getVersionsFilePath", { enumerable: true, get: function () { return versions_1.getVersionsFilePath; } });
+Object.defineProperty(exports, "readVersionsFile", { enumerable: true, get: function () { return versions_1.readVersionsFile; } });
+Object.defineProperty(exports, "readVersionNames", { enumerable: true, get: function () { return versions_1.readVersionNames; } });

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

@@ -4,12 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { 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;
-};
 export declare const DefaultSidebarItemsGenerator: SidebarItemsGenerator;

package/lib/sidebars/generator.js

@@ -0,0 +1,193 @@
+"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 = tslib_1.__importDefault(require("lodash"));
+const utils_1 = require("@docusaurus/utils");
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const path_1 = tslib_1.__importDefault(require("path"));
+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 = async ({ 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}.\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) {
+            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_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[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_label: label, sidebar_class_name: className }, } = getDoc(id);
+            return {
+                type: 'doc',
+                id,
+                position,
+                source: fileName,
+                // We don't want these fields to magically appear in the generated
+                // sidebar
+                ...(label !== undefined && { label }),
+                ...(className !== undefined && { className }),
+            };
+        }
+        function createCategoryItem(dir, fullPath, folderName) {
+            const categoryMetadata = categoriesMetadata[(0, utils_1.posixPath)(path_1.default.join(autogenDir, fullPath))];
+            const className = categoryMetadata?.className;
+            const { filename, numberPrefix } = numberPrefixParser(folderName);
+            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));
+                });
+            }
+            function getCategoryLinkedDocId() {
+                const link = categoryMetadata?.link;
+                if (link !== undefined) {
+                    if (link && link.type === 'doc') {
+                        return findDocByLocalId(link.id)?.id || getDoc(link.id).id;
+                    }
+                    // If a link is explicitly specified, we won't apply conventions
+                    return undefined;
+                }
+                // Apply default convention to pick index.md, README.md or
+                // <categoryName>.md as the category doc
+                return findConventionalCategoryDocLink()?.id;
+            }
+            const categoryLinkedDocId = getCategoryLinkedDocId();
+            const link = categoryLinkedDocId
+                ? {
+                    type: 'doc',
+                    id: categoryLinkedDocId, // 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 === categoryLinkedDocId));
+            return {
+                type: 'category',
+                label: categoryMetadata?.label ?? filename,
+                collapsible: categoryMetadata?.collapsible,
+                collapsed: categoryMetadata?.collapsed,
+                position: categoryMetadata?.position ?? numberPrefix,
+                source: folderName,
+                ...(className !== undefined && { className }),
+                items,
+                ...(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 { SidebarsConfig, Sidebars, SidebarProcessorParams } from './types';
+import type { PluginOptions } from '@docusaurus/plugin-content-docs';
+export declare const DefaultSidebars: SidebarsConfig;
+export declare const DisabledSidebars: SidebarsConfig;
+export declare function resolveSidebarPathOption(siteDir: string, sidebarPathOption: PluginOptions['sidebarPath']): PluginOptions['sidebarPath'];
+export declare function loadSidebarsFileUnsafe(sidebarFilePath: string | false | undefined): Promise<SidebarsConfig>;
+export declare function loadSidebars(sidebarFilePath: string | false | undefined, options: SidebarProcessorParams): Promise<Sidebars>;