@docusaurus/plugin-content-docs 2.0.0-beta.1 → 2.0.0-beta.10

package/lib/index.js

@@ -8,29 +8,31 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateOptions = void 0;
 const tslib_1 = require("tslib");
-const path_1 = tslib_1.__importDefault(require("path"));
-const constants_1 = require("@docusaurus/core/lib/constants");
+const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const utils_1 = require("@docusaurus/utils");
 const sidebars_1 = require("./sidebars");
+const generator_1 = require("./sidebars/generator");
 const docs_1 = require("./docs");
 const versions_1 = require("./versions");
 const cli_1 = require("./cli");
-const constants_2 = require("./constants");
+const constants_1 = require("./constants");
 const lodash_1 = require("lodash");
 const globalData_1 = require("./globalData");
 const props_1 = require("./props");
 const translations_1 = require("./translations");
-const sidebarItemsGenerator_1 = require("./sidebarItemsGenerator");
-const chalk_1 = tslib_1.__importDefault(require("chalk"));
+const chalk_1 = (0, tslib_1.__importDefault)(require("chalk"));
+const tags_1 = require("./tags");
+const routes_1 = require("./routes");
+const utils_2 = require("./sidebars/utils");
+const categoryGeneratedIndex_1 = require("./categoryGeneratedIndex");
 function pluginContentDocs(context, options) {
     var _a;
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
-    const versionsMetadata = versions_1.readVersionsMetadata({ context, options });
-    const sourceToPermalink = {};
-    const pluginId = (_a = options.id) !== null && _a !== void 0 ? _a : constants_1.DEFAULT_PLUGIN_ID;
+    const versionsMetadata = (0, versions_1.readVersionsMetadata)({ context, options });
+    const pluginId = (_a = options.id) !== null && _a !== void 0 ? _a : utils_1.DEFAULT_PLUGIN_ID;
     const pluginDataDirRoot = path_1.default.join(generatedFilesDir, 'docusaurus-plugin-content-docs');
     const dataDir = path_1.default.join(pluginDataDirRoot, pluginId);
-    const aliasedSource = (source) => `~docs/${utils_1.posixPath(path_1.default.relative(pluginDataDirRoot, source))}`;
+    const aliasedSource = (source) => `~docs/${(0, utils_1.posixPath)(path_1.default.relative(pluginDataDirRoot, source))}`;
     return {
         name: 'docusaurus-plugin-content-docs',
         getThemePath() {
@@ -40,7 +42,7 @@ function pluginContentDocs(context, options) {
             return path_1.default.resolve(__dirname, '..', 'src', 'theme');
         },
         extendCli(cli) {
-            const isDefaultPluginId = pluginId === constants_1.DEFAULT_PLUGIN_ID;
+            const isDefaultPluginId = pluginId === utils_1.DEFAULT_PLUGIN_ID;
             // Need to create one distinct command per plugin instance
             // otherwise 2 instances would try to execute the command!
             const command = isDefaultPluginId
@@ -54,43 +56,38 @@ function pluginContentDocs(context, options) {
                 .arguments('<version>')
                 .description(commandDescription)
                 .action((version) => {
-                cli_1.cliDocsVersionCommand(version, siteDir, pluginId, {
+                (0, cli_1.cliDocsVersionCommand)(version, siteDir, pluginId, {
                     path: options.path,
                     sidebarPath: options.sidebarPath,
+                    sidebarCollapsed: options.sidebarCollapsed,
+                    sidebarCollapsible: options.sidebarCollapsible,
                 });
             });
         },
         async getTranslationFiles({ content }) {
-            return translations_1.getLoadedContentTranslationFiles(content);
-        },
-        getClientModules() {
-            const modules = [];
-            if (options.admonitions) {
-                modules.push(require.resolve('remark-admonitions/styles/infima.css'));
-            }
-            return modules;
+            return (0, translations_1.getLoadedContentTranslationFiles)(content);
         },
         getPathsToWatch() {
             function getVersionPathsToWatch(version) {
                 const result = [
-                    ...lodash_1.flatten(options.include.map((pattern) => versions_1.getDocsDirPaths(version).map((docsDirPath) => `${docsDirPath}/${pattern}`))),
-                    `${version.contentPath}/**/${sidebarItemsGenerator_1.CategoryMetadataFilenamePattern}`,
+                    ...options.include.flatMap((pattern) => (0, versions_1.getDocsDirPaths)(version).map((docsDirPath) => `${docsDirPath}/${pattern}`)),
+                    `${version.contentPath}/**/${generator_1.CategoryMetadataFilenamePattern}`,
                 ];
                 if (typeof version.sidebarFilePath === 'string') {
                     result.unshift(version.sidebarFilePath);
                 }
                 return result;
             }
-            return lodash_1.flatten(versionsMetadata.map(getVersionPathsToWatch));
+            return versionsMetadata.flatMap(getVersionPathsToWatch);
         },
         async loadContent() {
             async function loadVersionDocsBase(versionMetadata) {
-                const docFiles = await docs_1.readVersionDocs(versionMetadata, options);
+                const docFiles = await (0, docs_1.readVersionDocs)(versionMetadata, options);
                 if (docFiles.length === 0) {
                     throw new Error(`Docs version "${versionMetadata.versionName}" has no docs! At least one doc should exist at "${path_1.default.relative(siteDir, versionMetadata.contentPath)}".`);
                 }
                 async function processVersionDoc(docFile) {
-                    return docs_1.processDocMetadata({
+                    return (0, docs_1.processDocMetadata)({
                         docFile,
                         versionMetadata,
                         context,
@@ -100,76 +97,28 @@ function pluginContentDocs(context, options) {
                 return Promise.all(docFiles.map(processVersionDoc));
             }
             async function doLoadVersion(versionMetadata) {
-                const unprocessedSidebars = sidebars_1.loadSidebars(versionMetadata.sidebarFilePath);
-                const docsBase = await loadVersionDocsBase(versionMetadata);
-                const docsBaseById = lodash_1.keyBy(docsBase, (doc) => doc.id);
-                const sidebars = await sidebars_1.processSidebars({
+                const docs = await loadVersionDocsBase(versionMetadata);
+                const sidebars = await (0, sidebars_1.loadSidebars)(versionMetadata.sidebarFilePath, {
                     sidebarItemsGenerator: options.sidebarItemsGenerator,
                     numberPrefixParser: options.numberPrefixParser,
-                    unprocessedSidebars,
-                    docs: docsBase,
+                    docs,
                     version: versionMetadata,
+                    sidebarOptions: {
+                        sidebarCollapsed: options.sidebarCollapsed,
+                        sidebarCollapsible: options.sidebarCollapsible,
+                    },
+                    categoryLabelSlugger: (0, utils_1.createSlugger)(),
                 });
-                const sidebarsUtils = sidebars_1.createSidebarsUtils(sidebars);
-                const validDocIds = Object.keys(docsBaseById);
-                sidebarsUtils.checkSidebarsDocIds(validDocIds, versionMetadata.sidebarFilePath);
-                // Add sidebar/next/previous to the docs
-                function addNavData(doc) {
-                    const { sidebarName, previousId, nextId, } = sidebarsUtils.getDocNavigation(doc.id);
-                    const toDocNavLink = (navDocId) => {
-                        var _a, _b;
-                        const { title, permalink, frontMatter } = docsBaseById[navDocId];
-                        return {
-                            title: (_b = (_a = frontMatter.pagination_label) !== null && _a !== void 0 ? _a : frontMatter.sidebar_label) !== null && _b !== void 0 ? _b : title,
-                            permalink,
-                        };
-                    };
-                    return {
-                        ...doc,
-                        sidebar: sidebarName,
-                        previous: previousId ? toDocNavLink(previousId) : undefined,
-                        next: nextId ? toDocNavLink(nextId) : undefined,
-                    };
-                }
-                const docs = docsBase.map(addNavData);
-                // sort to ensure consistent output for tests
-                docs.sort((a, b) => a.id.localeCompare(b.id));
-                // TODO annoying side effect!
-                Object.values(docs).forEach((loadedDoc) => {
-                    const { source, permalink } = loadedDoc;
-                    sourceToPermalink[source] = permalink;
-                });
-                // TODO really useful? replace with global state logic?
-                const permalinkToSidebar = {};
-                Object.values(docs).forEach((doc) => {
-                    if (doc.sidebar) {
-                        permalinkToSidebar[doc.permalink] = doc.sidebar;
-                    }
-                });
-                // The "main doc" is the "version entry point"
-                // We browse this doc by clicking on a version:
-                // - the "home" doc (at '/docs/')
-                // - the first doc of the first sidebar
-                // - a random doc (if no docs are in any sidebar... edge case)
-                function getMainDoc() {
-                    const versionHomeDoc = docs.find((doc) => doc.unversionedId === options.homePageId || doc.slug === '/');
-                    const firstDocIdOfFirstSidebar = sidebarsUtils.getFirstDocIdOfFirstSidebar();
-                    if (versionHomeDoc) {
-                        return versionHomeDoc;
-                    }
-                    else if (firstDocIdOfFirstSidebar) {
-                        return docs.find((doc) => doc.id === firstDocIdOfFirstSidebar);
-                    }
-                    else {
-                        return docs[0];
-                    }
-                }
+                const sidebarsUtils = (0, utils_2.createSidebarsUtils)(sidebars);
                 return {
                     ...versionMetadata,
-                    mainDocId: getMainDoc().unversionedId,
+                    docs: (0, docs_1.addDocNavigation)(docs, sidebarsUtils, versionMetadata.sidebarFilePath),
                     sidebars,
-                    permalinkToSidebar,
-                    docs: docs.map(addNavData),
+                    mainDocId: (0, docs_1.getMainDocId)({ docs, sidebarsUtils }),
+                    categoryGeneratedIndices: (0, categoryGeneratedIndex_1.getCategoryGeneratedIndexMetadataList)({
+                        docs,
+                        sidebarsUtils,
+                    }),
                 };
             }
             async function loadVersion(versionMetadata) {
@@ -186,81 +135,96 @@ function pluginContentDocs(context, options) {
             };
         },
         translateContent({ content, translationFiles }) {
-            return translations_1.translateLoadedContent(content, translationFiles);
+            return (0, translations_1.translateLoadedContent)(content, translationFiles);
         },
         async contentLoaded({ content, actions }) {
             const { loadedVersions } = content;
-            const { docLayoutComponent, docItemComponent } = options;
+            const { docLayoutComponent, docItemComponent, docCategoryGeneratedIndexComponent, } = options;
             const { addRoute, createData, setGlobalData } = actions;
-            const createDocRoutes = async (docs) => {
-                const routes = await Promise.all(docs.map(async (metadataItem) => {
-                    await createData(
-                    // Note that this created data path must be in sync with
-                    // metadataPath provided to mdx-loader.
-                    `${utils_1.docuHash(metadataItem.source)}.json`, JSON.stringify(metadataItem, null, 2));
-                    return {
-                        path: metadataItem.permalink,
-                        component: docItemComponent,
+            async function createVersionTagsRoutes(version) {
+                const versionTags = (0, tags_1.getVersionTags)(version.docs);
+                // TODO tags should be a sub route of the version route
+                async function createTagsListPage() {
+                    const tagsProp = Object.values(versionTags).map((tagValue) => ({
+                        name: tagValue.name,
+                        permalink: tagValue.permalink,
+                        count: tagValue.docIds.length,
+                    }));
+                    // Only create /tags page if there are tags.
+                    if (Object.keys(tagsProp).length > 0) {
+                        const tagsPropPath = await createData(`${(0, utils_1.docuHash)(`tags-list-${version.versionName}-prop`)}.json`, JSON.stringify(tagsProp, null, 2));
+                        addRoute({
+                            path: version.tagsPath,
+                            exact: true,
+                            component: options.docTagsListComponent,
+                            modules: {
+                                tags: aliasedSource(tagsPropPath),
+                            },
+                        });
+                    }
+                }
+                // TODO tags should be a sub route of the version route
+                async function createTagDocListPage(tag) {
+                    const tagProps = (0, props_1.toTagDocListProp)({
+                        allTagsPath: version.tagsPath,
+                        tag,
+                        docs: version.docs,
+                    });
+                    const tagPropPath = await createData(`${(0, utils_1.docuHash)(`tag-${tag.permalink}`)}.json`, JSON.stringify(tagProps, null, 2));
+                    addRoute({
+                        path: tag.permalink,
+                        component: options.docTagDocListComponent,
                         exact: true,
                         modules: {
-                            content: metadataItem.source,
+                            tag: aliasedSource(tagPropPath),
                         },
-                    };
-                }));
-                return routes.sort((a, b) => a.path.localeCompare(b.path));
-            };
-            async function doCreateVersionRoutes(loadedVersion) {
-                const versionMetadataPropPath = await createData(`${utils_1.docuHash(`version-${loadedVersion.versionName}-metadata-prop`)}.json`, JSON.stringify(props_1.toVersionMetadataProp(pluginId, loadedVersion), null, 2));
-                addRoute({
-                    path: loadedVersion.versionPath,
-                    // allow matching /docs/* as well
-                    exact: false,
-                    // main docs component (DocPage)
-                    component: docLayoutComponent,
-                    // sub-routes for each doc
-                    routes: await createDocRoutes(loadedVersion.docs),
-                    modules: {
-                        versionMetadata: aliasedSource(versionMetadataPropPath),
-                    },
-                    priority: loadedVersion.routePriority,
-                });
-            }
-            async function createVersionRoutes(loadedVersion) {
-                try {
-                    return await doCreateVersionRoutes(loadedVersion);
-                }
-                catch (e) {
-                    console.error(chalk_1.default.red(`Can't create version routes for version "${loadedVersion.versionName}"`));
-                    throw e;
+                    });
                 }
+                await createTagsListPage();
+                await Promise.all(Object.values(versionTags).map(createTagDocListPage));
             }
-            await Promise.all(loadedVersions.map(createVersionRoutes));
+            await Promise.all(loadedVersions.map((loadedVersion) => (0, routes_1.createVersionRoutes)({
+                loadedVersion,
+                docItemComponent,
+                docLayoutComponent,
+                docCategoryGeneratedIndexComponent,
+                pluginId,
+                aliasedSource,
+                actions,
+            })));
+            // TODO tags should be a sub route of the version route
+            await Promise.all(loadedVersions.map(createVersionTagsRoutes));
             setGlobalData({
-                path: utils_1.normalizeUrl([baseUrl, options.routeBasePath]),
+                path: (0, utils_1.normalizeUrl)([baseUrl, options.routeBasePath]),
                 versions: loadedVersions.map(globalData_1.toGlobalDataVersion),
             });
         },
-        configureWebpack(_config, isServer, utils) {
+        configureWebpack(_config, isServer, utils, content) {
             const { getJSLoader } = utils;
             const { rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
+            function getSourceToPermalink() {
+                const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+                return (0, lodash_1.mapValues)((0, lodash_1.keyBy)(allDocs, (d) => d.source), (d) => d.permalink);
+            }
             const docsMarkdownOptions = {
                 siteDir,
-                sourceToPermalink,
+                sourceToPermalink: getSourceToPermalink(),
                 versionsMetadata,
                 onBrokenMarkdownLink: (brokenMarkdownLink) => {
                     if (siteConfig.onBrokenMarkdownLinks === 'ignore') {
                         return;
                     }
-                    utils_1.reportMessage(`Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.contentPaths.versionName}`, siteConfig.onBrokenMarkdownLinks);
+                    (0, utils_1.reportMessage)(`Docs markdown link couldn't be resolved: (${brokenMarkdownLink.link}) in ${brokenMarkdownLink.filePath} for version ${brokenMarkdownLink.contentPaths.versionName}`, siteConfig.onBrokenMarkdownLinks);
                 },
             };
             function createMDXLoaderRule() {
+                const contentDirs = versionsMetadata.flatMap(versions_1.getDocsDirPaths);
                 return {
                     test: /(\.mdx?)$/,
-                    include: lodash_1.flatten(versionsMetadata.map(versions_1.getDocsDirPaths))
+                    include: contentDirs
                         // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
                         .map(utils_1.addTrailingPathSeparator),
-                    use: lodash_1.compact([
+                    use: [
                         getJSLoader({ isServer }),
                         {
                             loader: require.resolve('@docusaurus/mdx-loader'),
@@ -269,12 +233,14 @@ function pluginContentDocs(context, options) {
                                 rehypePlugins,
                                 beforeDefaultRehypePlugins,
                                 beforeDefaultRemarkPlugins,
-                                staticDir: path_1.default.join(siteDir, constants_1.STATIC_DIR_NAME),
+                                staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
+                                siteDir,
+                                isMDXPartial: (0, utils_1.createAbsoluteFilePathMatcher)(options.exclude, contentDirs),
                                 metadataPath: (mdxPath) => {
                                     // Note that metadataPath must be the same/in-sync as
                                     // the path from createData for each MDX.
-                                    const aliasedPath = utils_1.aliasedSitePath(mdxPath, siteDir);
-                                    return path_1.default.join(dataDir, `${utils_1.docuHash(aliasedPath)}.json`);
+                                    const aliasedPath = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
+                                    return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
                                 },
                             },
                         },
@@ -282,14 +248,14 @@ function pluginContentDocs(context, options) {
                             loader: path_1.default.resolve(__dirname, './markdown/index.js'),
                             options: docsMarkdownOptions,
                         },
-                    ]),
+                    ].filter(Boolean),
                 };
             }
             return {
                 ignoreWarnings: [
                     // Suppress warnings about non-existing of versions file.
                     (e) => e.message.includes("Can't resolve") &&
-                        e.message.includes(constants_2.VERSIONS_JSON_FILE),
+                        e.message.includes(constants_1.VERSIONS_JSON_FILE),
                 ],
                 resolve: {
                     alias: {

package/lib/lastUpdate.js

@@ -8,9 +8,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getFileLastUpdate = void 0;
 const tslib_1 = require("tslib");
-const shelljs_1 = tslib_1.__importDefault(require("shelljs"));
-const execa_1 = tslib_1.__importDefault(require("execa"));
-const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+), (.+)$/;
+const shelljs_1 = (0, tslib_1.__importDefault)(require("shelljs"));
+const GIT_COMMIT_TIMESTAMP_AUTHOR_REGEX = /^(\d+),(.+)$/;
 let showedGitRequirementError = false;
 async function getFileLastUpdate(filePath) {
     if (!filePath) {
@@ -35,13 +34,13 @@ async function getFileLastUpdate(filePath) {
             }
             return null;
         }
-        const { stdout } = await execa_1.default('git', [
-            'log',
-            '-1',
-            '--format=%ct, %an',
-            filePath,
-        ]);
-        return getTimestampAndAuthor(stdout);
+        const result = shelljs_1.default.exec(`git log -1 --format=%ct,%an ${filePath}`, {
+            silent: true,
+        });
+        if (result.code !== 0) {
+            throw new Error(`Retrieval of git history failed at ${filePath} with exit code ${result.code}: ${result.stderr}`);
+        }
+        return getTimestampAndAuthor(result.stdout.trim());
     }
     catch (error) {
         console.error(error);

package/lib/markdown/index.d.ts

@@ -4,9 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="node" />
-interface Loader extends Function {
-    (this: any, source: string): string | Buffer | void | undefined;
-}
-declare const markdownLoader: Loader;
-export default markdownLoader;
+import { DocsMarkdownOption } from '../types';
+import type { LoaderContext } from 'webpack';
+export default function markdownLoader(this: LoaderContext<DocsMarkdownOption>, source: string): void;

package/lib/markdown/index.js

@@ -7,10 +7,10 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 const linkify_1 = require("./linkify");
-const markdownLoader = function (source) {
+function markdownLoader(source) {
     const fileString = source;
     const callback = this.async();
     const options = this.getOptions();
-    return (callback && callback(null, linkify_1.linkify(fileString, this.resourcePath, options)));
-};
+    return (callback && callback(null, (0, linkify_1.linkify)(fileString, this.resourcePath, options)));
+}
 exports.default = markdownLoader;

package/lib/markdown/linkify.js

@@ -10,7 +10,7 @@ exports.linkify = void 0;
 const versions_1 = require("../versions");
 const utils_1 = require("@docusaurus/utils");
 function getVersion(filePath, options) {
-    const versionFound = options.versionsMetadata.find((version) => versions_1.getDocsDirPaths(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
+    const versionFound = options.versionsMetadata.find((version) => (0, versions_1.getDocsDirPaths)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
     if (!versionFound) {
         throw new Error(`Unexpected error: Markdown file at "${filePath}" does not belong to any docs version!`);
     }
@@ -18,7 +18,7 @@ function getVersion(filePath, options) {
 }
 function linkify(fileString, filePath, options) {
     const { siteDir, sourceToPermalink, onBrokenMarkdownLink } = options;
-    const { newContent, brokenMarkdownLinks } = utils_1.replaceMarkdownLinks({
+    const { newContent, brokenMarkdownLinks } = (0, utils_1.replaceMarkdownLinks)({
         siteDir,
         fileString,
         filePath,

package/lib/numberPrefix.d.ts

@@ -4,7 +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 { NumberPrefixParser } from './types';
+import type { NumberPrefixParser } from './types';
 export declare const DefaultNumberPrefixParser: NumberPrefixParser;
 export declare const DisabledNumberPrefixParser: NumberPrefixParser;
 export declare function stripNumberPrefix(str: string, parser: NumberPrefixParser): string;

package/lib/options.d.ts

@@ -4,9 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { PluginOptions } from './types';
+import type { PluginOptions } from './types';
 import { Joi } from '@docusaurus/utils-validation';
-import { OptionValidationContext, ValidationResult } from '@docusaurus/types';
+import type { OptionValidationContext, ValidationResult } from '@docusaurus/types';
 export declare const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'>;
 export declare const OptionsSchema: Joi.ObjectSchema<any>;
-export declare function validateOptions({ validate, options, }: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions>;
+export declare function validateOptions({ validate, options: userOptions, }: OptionValidationContext<PluginOptions>): ValidationResult<PluginOptions>;

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 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',
-    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: [],
@@ -23,17 +34,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 +62,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 +81,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),
@@ -69,22 +93,30 @@ 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, }) {
-    // 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;
+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,
+            };
+        }
     }
     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;