@docusaurus/plugin-content-docs 3.3.2 → 3.5.0

package/lib/index.js

@@ -7,11 +7,13 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.validateOptions = void 0;
+exports.default = pluginContentDocs;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
+const utils_validation_1 = require("@docusaurus/utils-validation");
 const sidebars_1 = require("./sidebars");
 const generator_1 = require("./sidebars/generator");
 const docs_1 = require("./docs");
@@ -22,6 +24,25 @@ const globalData_1 = require("./globalData");
 const translations_1 = require("./translations");
 const routes_1 = require("./routes");
 const utils_2 = require("./sidebars/utils");
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to permalink is currently a mutable map passed to the mdx loader
+//  for link resolution
+//  see https://github.com/facebook/docusaurus/pull/10185
+function createSourceToPermalinkHelper() {
+    const sourceToPermalink = new Map();
+    function computeSourceToPermalink(content) {
+        const allDocs = content.loadedVersions.flatMap((v) => v.docs);
+        return new Map(allDocs.map(({ source, permalink }) => [source, permalink]));
+    }
+    // Mutable map update :/
+    function update(content) {
+        sourceToPermalink.clear();
+        computeSourceToPermalink(content).forEach((value, key) => {
+            sourceToPermalink.set(key, value);
+        });
+    }
+    return { get: () => sourceToPermalink, update };
+}
 async function pluginContentDocs(context, options) {
     const { siteDir, generatedFilesDir, baseUrl, siteConfig } = context;
     // Mutate options to resolve sidebar path according to siteDir
@@ -36,6 +57,7 @@ async function pluginContentDocs(context, options) {
     const aliasedSource = (source) => `~docs/${(0, utils_1.posixPath)(path_1.default.relative(pluginDataDirRoot, source))}`;
     // TODO env should be injected into all plugins
     const env = process.env.NODE_ENV;
+    const sourceToPermalinkHelper = createSourceToPermalinkHelper();
     return {
         name: 'docusaurus-plugin-content-docs',
         extendCli(cli) {
@@ -61,6 +83,10 @@ async function pluginContentDocs(context, options) {
             function getVersionPathsToWatch(version) {
                 const result = [
                     ...options.include.flatMap((pattern) => (0, utils_1.getContentPathList)(version).map((docsDirPath) => `${docsDirPath}/${pattern}`)),
+                    ...(0, utils_validation_1.getTagsFilePathsToWatch)({
+                        contentPaths: version,
+                        tags: options.tags,
+                    }),
                     `${version.contentPath}/**/${generator_1.CategoryMetadataFilenamePattern}`,
                 ];
                 if (typeof version.sidebarFilePath === 'string') {
@@ -71,7 +97,7 @@ async function pluginContentDocs(context, options) {
             return versionsMetadata.flatMap(getVersionPathsToWatch);
         },
         async loadContent() {
-            async function loadVersionDocsBase(versionMetadata) {
+            async function loadVersionDocsBase(versionMetadata, tagsFile) {
                 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)}".`);
@@ -83,12 +109,17 @@ async function pluginContentDocs(context, options) {
                         context,
                         options,
                         env,
+                        tagsFile,
                     });
                 }
                 return Promise.all(docFiles.map(processVersionDoc));
             }
             async function doLoadVersion(versionMetadata) {
-                const docsBase = await loadVersionDocsBase(versionMetadata);
+                const tagsFile = await (0, utils_validation_1.getTagsFile)({
+                    contentPaths: versionMetadata,
+                    tags: options.tags,
+                });
+                const docsBase = await loadVersionDocsBase(versionMetadata, tagsFile);
                 // TODO we only ever need draftIds in further code, not full draft items
                 // To simplify and prevent mistakes, avoid exposing draft
                 // replace draft=>draftIds in content loaded
@@ -144,6 +175,7 @@ async function pluginContentDocs(context, options) {
             return (0, translations_1.translateLoadedContent)(content, translationFiles);
         },
         async contentLoaded({ content, actions }) {
+            sourceToPermalinkHelper.update(content);
             const versions = content.loadedVersions.map(versions_1.toFullVersion);
             await (0, routes_1.createAllRoutes)({
                 baseUrl,
@@ -159,58 +191,51 @@ async function pluginContentDocs(context, options) {
             });
         },
         configureWebpack(_config, isServer, utils, content) {
-            const { rehypePlugins, remarkPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
-            function getSourceToPermalink() {
-                const allDocs = content.loadedVersions.flatMap((v) => v.docs);
-                return Object.fromEntries(allDocs.map(({ source, permalink }) => [source, permalink]));
-            }
-            const docsMarkdownOptions = {
-                siteDir,
-                sourceToPermalink: getSourceToPermalink(),
-                versionsMetadata,
-                onBrokenMarkdownLink: (brokenMarkdownLink) => {
-                    logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${brokenMarkdownLink.link}) in path=${brokenMarkdownLink.filePath} for version number=${brokenMarkdownLink.contentPaths.versionName}`;
-                },
-            };
-            function createMDXLoaderRule() {
-                const contentDirs = versionsMetadata
-                    .flatMap(utils_1.getContentPathList)
-                    // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
-                    .map(utils_1.addTrailingPathSeparator);
+            const { rehypePlugins, remarkPlugins, recmaPlugins, beforeDefaultRehypePlugins, beforeDefaultRemarkPlugins, } = options;
+            const contentDirs = versionsMetadata
+                .flatMap(utils_1.getContentPathList)
+                // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
+                .map(utils_1.addTrailingPathSeparator);
+            function createMDXLoader() {
+                const loaderOptions = {
+                    admonitions: options.admonitions,
+                    remarkPlugins,
+                    rehypePlugins,
+                    recmaPlugins,
+                    beforeDefaultRehypePlugins,
+                    beforeDefaultRemarkPlugins,
+                    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 = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
+                        return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
+                    },
+                    // Assets allow to convert some relative images paths to
+                    // require(...) calls
+                    createAssets: ({ frontMatter }) => ({
+                        image: frontMatter.image,
+                    }),
+                    markdownConfig: siteConfig.markdown,
+                    resolveMarkdownLink: ({ linkPathname, sourceFilePath }) => {
+                        const version = (0, versions_1.getVersionFromSourceFilePath)(sourceFilePath, content.loadedVersions);
+                        const permalink = (0, utils_1.resolveMarkdownLinkPathname)(linkPathname, {
+                            sourceFilePath,
+                            sourceToPermalink: sourceToPermalinkHelper.get(),
+                            siteDir,
+                            contentPaths: version,
+                        });
+                        if (permalink === null) {
+                            logger_1.default.report(siteConfig.onBrokenMarkdownLinks) `Docs markdown link couldn't be resolved: (url=${linkPathname}) in source file path=${sourceFilePath} for version number=${version.versionName}`;
+                        }
+                        return permalink;
+                    },
+                };
                 return {
-                    test: /\.mdx?$/i,
-                    include: contentDirs,
-                    use: [
-                        {
-                            loader: require.resolve('@docusaurus/mdx-loader'),
-                            options: {
-                                admonitions: options.admonitions,
-                                remarkPlugins,
-                                rehypePlugins,
-                                beforeDefaultRehypePlugins,
-                                beforeDefaultRemarkPlugins,
-                                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 = (0, utils_1.aliasedSitePath)(mdxPath, siteDir);
-                                    return path_1.default.join(dataDir, `${(0, utils_1.docuHash)(aliasedPath)}.json`);
-                                },
-                                // Assets allow to convert some relative images paths to
-                                // require(...) calls
-                                createAssets: ({ frontMatter, }) => ({
-                                    image: frontMatter.image,
-                                }),
-                                markdownConfig: siteConfig.markdown,
-                            },
-                        },
-                        {
-                            loader: path_1.default.resolve(__dirname, './markdown/index.js'),
-                            options: docsMarkdownOptions,
-                        },
-                    ].filter(Boolean),
+                    loader: require.resolve('@docusaurus/mdx-loader'),
+                    options: loaderOptions,
                 };
             }
             return {
@@ -225,12 +250,17 @@ async function pluginContentDocs(context, options) {
                     },
                 },
                 module: {
-                    rules: [createMDXLoaderRule()],
+                    rules: [
+                        {
+                            test: /\.mdx?$/i,
+                            include: contentDirs,
+                            use: [createMDXLoader()],
+                        },
+                    ],
                 },
             };
         },
     };
 }
-exports.default = pluginContentDocs;
 var options_1 = require("./options");
 Object.defineProperty(exports, "validateOptions", { enumerable: true, get: function () { return options_1.validateOptions; } });

package/lib/numberPrefix.d.ts

@@ -4,7 +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 path="../src/plugin-content-docs.d.ts" />
 import type { NumberPrefixParser } from '@docusaurus/plugin-content-docs';
 export declare const DefaultNumberPrefixParser: NumberPrefixParser;
 export declare const DisabledNumberPrefixParser: NumberPrefixParser;

package/lib/numberPrefix.js

@@ -6,7 +6,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stripPathNumberPrefixes = exports.stripNumberPrefix = exports.DisabledNumberPrefixParser = exports.DefaultNumberPrefixParser = void 0;
+exports.DisabledNumberPrefixParser = exports.DefaultNumberPrefixParser = void 0;
+exports.stripNumberPrefix = stripNumberPrefix;
+exports.stripPathNumberPrefixes = stripPathNumberPrefixes;
 // Best-effort to avoid parsing some patterns as number prefix
 // ignore common date-like patterns: https://github.com/facebook/docusaurus/issues/4640
 // ignore common versioning patterns: https://github.com/facebook/docusaurus/issues/4653
@@ -39,7 +41,6 @@ exports.DisabledNumberPrefixParser = DisabledNumberPrefixParser;
 function stripNumberPrefix(str, parser) {
     return parser(str).filename;
 }
-exports.stripNumberPrefix = stripNumberPrefix;
 // 0-myFolder/0-mySubfolder/0-myDoc => myFolder/mySubfolder/myDoc
 function stripPathNumberPrefixes(path, parser) {
     return path
@@ -47,4 +48,3 @@ function stripPathNumberPrefixes(path, parser) {
         .map((segment) => stripNumberPrefix(segment, parser))
         .join('/');
 }
-exports.stripPathNumberPrefixes = stripPathNumberPrefixes;

package/lib/options.d.ts

@@ -4,7 +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 path="../src/plugin-content-docs.d.ts" />
 import type { OptionValidationContext } from '@docusaurus/types';
 import type { PluginOptions, Options } from '@docusaurus/plugin-content-docs';
 export declare const DEFAULT_OPTIONS: Omit<PluginOptions, 'id' | 'sidebarPath'>;

package/lib/options.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateOptions = exports.DEFAULT_OPTIONS = void 0;
+exports.DEFAULT_OPTIONS = void 0;
+exports.validateOptions = validateOptions;
 const tslib_1 = require("tslib");
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_validation_1 = require("@docusaurus/utils-validation");
@@ -30,6 +31,7 @@ exports.DEFAULT_OPTIONS = {
     docCategoryGeneratedIndexComponent: '@theme/DocCategoryGeneratedIndexPage',
     remarkPlugins: [],
     rehypePlugins: [],
+    recmaPlugins: [],
     beforeDefaultRemarkPlugins: [],
     beforeDefaultRehypePlugins: [],
     showLastUpdateTime: false,
@@ -44,6 +46,8 @@ exports.DEFAULT_OPTIONS = {
     sidebarCollapsible: true,
     sidebarCollapsed: true,
     breadcrumbs: true,
+    onInlineTags: 'warn',
+    tags: undefined,
 };
 const VersionOptionsSchema = utils_validation_1.Joi.object({
     path: utils_validation_1.Joi.string().allow('').optional(),
@@ -89,6 +93,7 @@ const OptionsSchema = utils_validation_1.Joi.object({
     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),
+    recmaPlugins: utils_validation_1.RecmaPluginsSchema.default(exports.DEFAULT_OPTIONS.recmaPlugins),
     beforeDefaultRemarkPlugins: utils_validation_1.RemarkPluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRemarkPlugins),
     beforeDefaultRehypePlugins: utils_validation_1.RehypePluginsSchema.default(exports.DEFAULT_OPTIONS.beforeDefaultRehypePlugins),
     admonitions: utils_validation_1.AdmonitionsSchema.default(exports.DEFAULT_OPTIONS.admonitions),
@@ -100,6 +105,13 @@ const OptionsSchema = utils_validation_1.Joi.object({
     lastVersion: utils_validation_1.Joi.string().optional(),
     versions: VersionsOptionsSchema,
     breadcrumbs: utils_validation_1.Joi.bool().default(exports.DEFAULT_OPTIONS.breadcrumbs),
+    onInlineTags: utils_validation_1.Joi.string()
+        .equal('ignore', 'log', 'warn', 'throw')
+        .default(exports.DEFAULT_OPTIONS.onInlineTags),
+    tags: utils_validation_1.Joi.string()
+        .disallow('')
+        .allow(null, false)
+        .default(() => exports.DEFAULT_OPTIONS.tags),
 });
 function validateOptions({ validate, options: userOptions, }) {
     let options = userOptions;
@@ -124,4 +136,3 @@ function validateOptions({ validate, options: userOptions, }) {
     const normalizedOptions = validate(OptionsSchema, options);
     return normalizedOptions;
 }
-exports.validateOptions = validateOptions;

package/lib/props.d.ts

@@ -4,7 +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 path="../src/plugin-content-docs.d.ts" />
 import type { VersionTag, VersionTags } from './types';
 import type { SidebarItemDoc } from './sidebars/types';
 import type { PropSidebars, PropVersionMetadata, PropTagDocList, PropTagsListPage, PropSidebarItemLink, DocMetadata, LoadedVersion } from '@docusaurus/plugin-content-docs';

package/lib/props.js

@@ -6,7 +6,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toTagsListTagsProp = exports.toTagDocListProp = exports.toVersionMetadataProp = exports.toSidebarsProp = exports.toSidebarDocItemLinkProp = void 0;
+exports.toSidebarDocItemLinkProp = toSidebarDocItemLinkProp;
+exports.toSidebarsProp = toSidebarsProp;
+exports.toVersionMetadataProp = toVersionMetadataProp;
+exports.toTagDocListProp = toTagDocListProp;
+exports.toTagsListTagsProp = toTagsListTagsProp;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const docs_1 = require("./docs");
@@ -22,7 +26,6 @@ function toSidebarDocItemLinkProp({ item, doc, }) {
         unlisted,
     };
 }
-exports.toSidebarDocItemLinkProp = toSidebarDocItemLinkProp;
 function toSidebarsProp(loadedVersion) {
     const docsById = (0, docs_1.createDocsByIdIndex)(loadedVersion.docs);
     function getDocById(docId) {
@@ -92,7 +95,6 @@ Available document ids are:
     // This is what will be passed as props to the UI component.
     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.id,
@@ -118,7 +120,6 @@ function toVersionMetadataProp(pluginId, loadedVersion) {
         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)));
@@ -134,20 +135,20 @@ function toTagDocListProp({ allTagsPath, tag, docs, }) {
     return {
         label: tag.label,
         permalink: tag.permalink,
+        description: tag.description,
         allTagsPath,
         count: tag.docIds.length,
         items: toDocListProp(),
         unlisted: tag.unlisted,
     };
 }
-exports.toTagDocListProp = toTagDocListProp;
 function toTagsListTagsProp(versionTags) {
     return Object.values(versionTags)
         .filter((tagValue) => !tagValue.unlisted)
         .map((tagValue) => ({
         label: tagValue.label,
         permalink: tagValue.permalink,
+        description: tagValue.description,
         count: tagValue.docIds.length,
     }));
 }
-exports.toTagsListTagsProp = toTagsListTagsProp;

package/lib/routes.d.ts

@@ -4,7 +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 path="../src/plugin-content-docs.d.ts" />
 import type { PluginContentLoadedActions, RouteConfig } from '@docusaurus/types';
 import type { FullVersion } from './types';
 import type { PluginOptions } from '@docusaurus/plugin-content-docs';

package/lib/routes.js

@@ -6,13 +6,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createAllRoutes = exports.buildAllRoutes = void 0;
+exports.buildAllRoutes = buildAllRoutes;
+exports.createAllRoutes = createAllRoutes;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const props_1 = require("./props");
-const tags_1 = require("./tags");
 function createDocRouteMetadata(docMeta) {
     return {
         sourceFilePath: (0, utils_1.aliasedSitePathToRelativePath)(docMeta.source),
@@ -74,12 +74,30 @@ async function buildVersionSidebarRoute(param) {
         routes: subRoutes,
     };
 }
+function getVersionTags(docs) {
+    const groups = (0, utils_1.groupTaggedItems)(docs, (doc) => doc.tags);
+    return lodash_1.default.mapValues(groups, ({ tag, items: tagDocs }) => {
+        const tagVisibility = (0, utils_1.getTagVisibility)({
+            items: tagDocs,
+            isUnlisted: (item) => item.unlisted,
+        });
+        return {
+            inline: tag.inline,
+            label: tag.label,
+            permalink: tag.permalink,
+            description: tag.description,
+            docIds: tagVisibility.listedItems.map((item) => item.id),
+            unlisted: tagVisibility.unlisted,
+        };
+    });
+}
 async function buildVersionTagsRoutes(param) {
     const { version, options } = param;
-    const versionTags = (0, tags_1.getVersionTags)(version.docs);
+    const versionTags = getVersionTags(version.docs);
     async function buildTagsListRoute() {
+        const tags = (0, props_1.toTagsListTagsProp)(versionTags);
         // Don't create a tags list page if there's no tag
-        if (Object.keys(versionTags).length === 0) {
+        if (tags.length === 0) {
             return null;
         }
         return {
@@ -87,7 +105,7 @@ async function buildVersionTagsRoutes(param) {
             exact: true,
             component: options.docTagsListComponent,
             props: {
-                tags: (0, props_1.toTagsListTagsProp)(versionTags),
+                tags,
             },
         };
     }
@@ -160,9 +178,7 @@ async function buildAllRoutes(param) {
         },
     ];
 }
-exports.buildAllRoutes = buildAllRoutes;
 async function createAllRoutes(param) {
     const routes = await buildAllRoutes(param);
     routes.forEach(param.actions.addRoute);
 }
-exports.createAllRoutes = createAllRoutes;

package/lib/sidebars/generator.js

@@ -168,6 +168,9 @@ Available doc IDs:
                 ...(customProps !== undefined && { customProps }),
                 ...(className !== undefined && { className }),
                 items,
+                ...(categoryMetadata?.description && {
+                    description: categoryMetadata?.description,
+                }),
                 ...(link && { link }),
             };
         }

package/lib/sidebars/index.d.ts

@@ -4,7 +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 path="../../src/plugin-content-docs.d.ts" />
 import type { PluginOptions } from '@docusaurus/plugin-content-docs';
 import type { SidebarsConfig, Sidebars, SidebarProcessorParams } from './types';
 export declare const DefaultSidebars: SidebarsConfig;

package/lib/sidebars/index.js

@@ -6,7 +6,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadSidebars = exports.loadSidebarsFile = exports.resolveSidebarPathOption = exports.DisabledSidebars = exports.DefaultSidebars = void 0;
+exports.DisabledSidebars = exports.DefaultSidebars = void 0;
+exports.resolveSidebarPathOption = resolveSidebarPathOption;
+exports.loadSidebarsFile = loadSidebarsFile;
+exports.loadSidebars = loadSidebars;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
@@ -34,7 +37,6 @@ function resolveSidebarPathOption(siteDir, sidebarPathOption) {
         ? path_1.default.resolve(siteDir, sidebarPathOption)
         : sidebarPathOption;
 }
-exports.resolveSidebarPathOption = resolveSidebarPathOption;
 async function readCategoriesMetadata(contentPath) {
     const categoryFiles = await (0, utils_1.Globby)('**/_category_.{json,yml,yaml}', {
         cwd: contentPath,
@@ -80,7 +82,6 @@ async function loadSidebarsFile(sidebarFilePath) {
     // TODO unsafe, need to refactor and improve validation
     return sidebars;
 }
-exports.loadSidebarsFile = loadSidebarsFile;
 async function loadSidebars(sidebarFilePath, options) {
     try {
         const sidebarsConfig = await loadSidebarsFileUnsafe(sidebarFilePath);
@@ -95,4 +96,3 @@ async function loadSidebars(sidebarFilePath, options) {
         throw err;
     }
 }
-exports.loadSidebars = loadSidebars;

package/lib/sidebars/normalization.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.normalizeSidebars = exports.normalizeItem = void 0;
+exports.normalizeItem = normalizeItem;
+exports.normalizeSidebars = normalizeSidebars;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
@@ -43,7 +44,6 @@ function normalizeItem(item) {
     }
     return [item];
 }
-exports.normalizeItem = normalizeItem;
 function normalizeSidebar(sidebar, place) {
     if (!Array.isArray(sidebar) && !(0, utils_1.isCategoriesShorthand)(sidebar)) {
         throw new Error(logger_1.default.interpolate `Invalid sidebar items collection code=${JSON.stringify(sidebar)} in ${place}: it must either be an array of sidebar items or a shorthand notation (which doesn't contain a code=${'type'} property). See url=${'https://docusaurus.io/docs/sidebar/items'} for all valid syntaxes.`);
@@ -56,4 +56,3 @@ function normalizeSidebar(sidebar, place) {
 function normalizeSidebars(sidebars) {
     return lodash_1.default.mapValues(sidebars, (sidebar, id) => normalizeSidebar(sidebar, logger_1.default.interpolate `sidebar name=${id}`));
 }
-exports.normalizeSidebars = normalizeSidebars;

package/lib/sidebars/postProcessor.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.postProcessSidebars = void 0;
+exports.postProcessSidebars = postProcessSidebars;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
@@ -77,4 +77,3 @@ function postProcessSidebars(sidebars, params) {
         .map((item) => postProcessSidebarItem(item, { ...params, draftIds }))
         .filter((v) => Boolean(v)));
 }
-exports.postProcessSidebars = postProcessSidebars;

package/lib/sidebars/processor.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processSidebars = void 0;
+exports.processSidebars = processSidebars;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
@@ -75,4 +75,3 @@ async function processSidebars(unprocessedSidebars, categoriesMetadata, params)
     (0, validation_1.validateSidebars)(processedSidebars);
     return processedSidebars;
 }
-exports.processSidebars = processSidebars;

package/lib/sidebars/types.d.ts

@@ -4,7 +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 path="../../src/plugin-content-docs.d.ts" />
 import type { Optional, Required } from 'utility-types';
 import type { NumberPrefixParser, SidebarOptions, CategoryIndexMatcher, DocMetadataBase, VersionMetadata } from '@docusaurus/plugin-content-docs';
 import type { Slugger } from '@docusaurus/utils';
@@ -139,6 +138,7 @@ export type PropSidebarBreadcrumbsItem = PropSidebarItemLink | PropSidebarItemCa
 export type CategoryMetadataFile = {
     label?: string;
     position?: number;
+    description?: string;
     collapsed?: boolean;
     collapsible?: boolean;
     className?: string;

package/lib/sidebars/utils.d.ts

@@ -4,7 +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 path="../../src/plugin-content-docs.d.ts" />
 import type { Sidebars, Sidebar, SidebarItem, SidebarItemCategory, SidebarItemLink, SidebarItemDoc, SidebarCategoriesShorthand, SidebarItemConfig, SidebarItemCategoryWithGeneratedIndex, SidebarNavigationItem } from './types';
 import type { DocMetadataBase, PropNavigationLink, VersionMetadata } from '@docusaurus/plugin-content-docs';
 export declare function isCategoriesShorthand(item: SidebarItemConfig): item is SidebarCategoriesShorthand;