@docusaurus/plugin-content-docs 3.4.0 → 3.5.1

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;

package/lib/sidebars/utils.js

@@ -6,14 +6,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toNavigationLink = exports.toDocNavigationLink = exports.createSidebarsUtils = exports.collectSidebarsNavigations = exports.collectSidebarsDocIds = exports.collectSidebarNavigation = exports.collectSidebarDocIds = exports.collectSidebarRefs = exports.collectSidebarLinks = exports.collectSidebarCategories = exports.collectSidebarDocItems = exports.transformSidebarItems = exports.isCategoriesShorthand = void 0;
+exports.isCategoriesShorthand = isCategoriesShorthand;
+exports.transformSidebarItems = transformSidebarItems;
+exports.collectSidebarDocItems = collectSidebarDocItems;
+exports.collectSidebarCategories = collectSidebarCategories;
+exports.collectSidebarLinks = collectSidebarLinks;
+exports.collectSidebarRefs = collectSidebarRefs;
+exports.collectSidebarDocIds = collectSidebarDocIds;
+exports.collectSidebarNavigation = collectSidebarNavigation;
+exports.collectSidebarsDocIds = collectSidebarsDocIds;
+exports.collectSidebarsNavigations = collectSidebarsNavigations;
+exports.createSidebarsUtils = createSidebarsUtils;
+exports.toDocNavigationLink = toDocNavigationLink;
+exports.toNavigationLink = toNavigationLink;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 function isCategoriesShorthand(item) {
     return typeof item === 'object' && !item.type;
 }
-exports.isCategoriesShorthand = isCategoriesShorthand;
 function transformSidebarItems(sidebar, updateFn) {
     function transformRecursive(item) {
         if (item.type === 'category') {
@@ -26,7 +37,6 @@ function transformSidebarItems(sidebar, updateFn) {
     }
     return sidebar.map(transformRecursive);
 }
-exports.transformSidebarItems = transformSidebarItems;
 /**
  * Flatten sidebar items into a single flat array (containing categories/docs on
  * the same level). Order matters (useful for next/prev nav), top categories
@@ -46,19 +56,15 @@ function collectSidebarItemsOfType(type, sidebar) {
 function collectSidebarDocItems(sidebar) {
     return collectSidebarItemsOfType('doc', sidebar);
 }
-exports.collectSidebarDocItems = collectSidebarDocItems;
 function collectSidebarCategories(sidebar) {
     return collectSidebarItemsOfType('category', sidebar);
 }
-exports.collectSidebarCategories = collectSidebarCategories;
 function collectSidebarLinks(sidebar) {
     return collectSidebarItemsOfType('link', sidebar);
 }
-exports.collectSidebarLinks = collectSidebarLinks;
 function collectSidebarRefs(sidebar) {
     return collectSidebarItemsOfType('ref', sidebar);
 }
-exports.collectSidebarRefs = collectSidebarRefs;
 // /!\ docId order matters for navigation!
 function collectSidebarDocIds(sidebar) {
     return flattenSidebarItems(sidebar).flatMap((item) => {
@@ -71,7 +77,6 @@ function collectSidebarDocIds(sidebar) {
         return [];
     });
 }
-exports.collectSidebarDocIds = collectSidebarDocIds;
 function collectSidebarNavigation(sidebar) {
     return flattenSidebarItems(sidebar).flatMap((item) => {
         if (item.type === 'category' && item.link) {
@@ -83,15 +88,12 @@ function collectSidebarNavigation(sidebar) {
         return [];
     });
 }
-exports.collectSidebarNavigation = collectSidebarNavigation;
 function collectSidebarsDocIds(sidebars) {
     return lodash_1.default.mapValues(sidebars, collectSidebarDocIds);
 }
-exports.collectSidebarsDocIds = collectSidebarsDocIds;
 function collectSidebarsNavigations(sidebars) {
     return lodash_1.default.mapValues(sidebars, collectSidebarNavigation);
 }
-exports.collectSidebarsNavigations = collectSidebarsNavigations;
 function createSidebarsUtils(sidebars) {
     const sidebarNameToDocIds = collectSidebarsDocIds(sidebars);
     const sidebarNameToNavigationItems = collectSidebarsNavigations(sidebars);
@@ -293,7 +295,6 @@ Available document ids are:
         getFirstLink: (id) => getFirstLink(sidebars[id]),
     };
 }
-exports.createSidebarsUtils = createSidebarsUtils;
 function toDocNavigationLink(doc, options) {
     const { title, permalink, frontMatter: { pagination_label: paginationLabel, sidebar_label: sidebarLabel, }, } = doc;
     return {
@@ -301,7 +302,6 @@ function toDocNavigationLink(doc, options) {
         permalink,
     };
 }
-exports.toDocNavigationLink = toDocNavigationLink;
 function toNavigationLink(navigationItem, docsById) {
     function getDocById(docId) {
         const doc = docsById[docId];
@@ -325,4 +325,3 @@ function toNavigationLink(navigationItem, docsById) {
         sidebarItemLabel: navigationItem?.label,
     });
 }
-exports.toNavigationLink = toNavigationLink;

package/lib/sidebars/validation.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateCategoryMetadataFile = exports.validateSidebars = void 0;
+exports.validateSidebars = validateSidebars;
+exports.validateCategoryMetadataFile = validateCategoryMetadataFile;
 const utils_validation_1 = require("@docusaurus/utils-validation");
 // NOTE: we don't add any default values during validation on purpose!
 // Config types are exposed to users for typechecking and we use the same type
@@ -130,9 +131,9 @@ function validateSidebars(sidebars) {
         sidebar.forEach(validateSidebarItem);
     });
 }
-exports.validateSidebars = validateSidebars;
 const categoryMetadataFileSchema = utils_validation_1.Joi.object({
     label: utils_validation_1.Joi.string(),
+    description: utils_validation_1.Joi.string(),
     position: utils_validation_1.Joi.number(),
     collapsed: utils_validation_1.Joi.boolean(),
     collapsible: utils_validation_1.Joi.boolean(),
@@ -147,4 +148,3 @@ function validateCategoryMetadataFile(unsafeContent) {
     }
     return value;
 }
-exports.validateCategoryMetadataFile = validateCategoryMetadataFile;

package/lib/slug.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, DocMetadataBase } from '@docusaurus/plugin-content-docs';
 export default function getSlug({ baseID, frontMatterSlug, source, sourceDirName, stripDirNumberPrefixes, numberPrefixParser, }: {
     baseID: string;

package/lib/slug.js

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = getSlug;
 const utils_1 = require("@docusaurus/utils");
 const utils_common_1 = require("@docusaurus/utils-common");
 const numberPrefix_1 = require("./numberPrefix");
@@ -48,4 +49,3 @@ slug: /my/customDocPath
     }
     return ensureValidSlug(computeSlug());
 }
-exports.default = getSlug;

package/lib/translations.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 { LoadedContent } from '@docusaurus/plugin-content-docs';
 import type { TranslationFile } from '@docusaurus/types';
 export declare function getLoadedContentTranslationFiles(loadedContent: LoadedContent): TranslationFile[];

package/lib/translations.js

@@ -6,7 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.translateLoadedContent = exports.getLoadedContentTranslationFiles = void 0;
+exports.getLoadedContentTranslationFiles = getLoadedContentTranslationFiles;
+exports.translateLoadedContent = translateLoadedContent;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
@@ -158,11 +159,9 @@ function translateVersions(versions, translationFiles) {
 function getLoadedContentTranslationFiles(loadedContent) {
     return getVersionsTranslationFiles(loadedContent.loadedVersions);
 }
-exports.getLoadedContentTranslationFiles = getLoadedContentTranslationFiles;
 function translateLoadedContent(loadedContent, translationFiles) {
     const translationFilesMap = lodash_1.default.keyBy(translationFiles, (f) => f.path);
     return {
         loadedVersions: translateVersions(loadedContent.loadedVersions, translationFilesMap),
     };
 }
-exports.translateLoadedContent = translateLoadedContent;

package/lib/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 { TagMetadata } from '@docusaurus/utils';
 import type { LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';

package/lib/versions/files.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, VersionMetadata } from '@docusaurus/plugin-content-docs';
 import type { VersionContext } from './index';
 /** `[siteDir]/community_versioned_docs/version-1.0.0` */

package/lib/versions/files.js

@@ -6,7 +6,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersionMetadataPaths = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getDocsDirPathLocalized = exports.getVersionSidebarsPath = exports.getVersionDocsDirPath = void 0;
+exports.getVersionDocsDirPath = getVersionDocsDirPath;
+exports.getVersionSidebarsPath = getVersionSidebarsPath;
+exports.getDocsDirPathLocalized = getDocsDirPathLocalized;
+exports.getVersionsFilePath = getVersionsFilePath;
+exports.readVersionsFile = readVersionsFile;
+exports.readVersionNames = readVersionNames;
+exports.getVersionMetadataPaths = getVersionMetadataPaths;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
@@ -23,12 +29,10 @@ function addPluginIdPrefix(fileOrDir, pluginId) {
 function getVersionDocsDirPath(siteDir, pluginId, versionName) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId), `version-${versionName}`);
 }
-exports.getVersionDocsDirPath = getVersionDocsDirPath;
 /** `[siteDir]/community_versioned_sidebars/version-1.0.0-sidebars.json` */
 function getVersionSidebarsPath(siteDir, pluginId, versionName) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_SIDEBARS_DIR, pluginId), `version-${versionName}-sidebars.json`);
 }
-exports.getVersionSidebarsPath = getVersionSidebarsPath;
 function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }) {
     return (0, utils_1.getPluginI18nPath)({
         localizationDir,
@@ -41,12 +45,10 @@ function getDocsDirPathLocalized({ localizationDir, pluginId, versionName, }) {
         ],
     });
 }
-exports.getDocsDirPathLocalized = getDocsDirPathLocalized;
 /** `community` => `[siteDir]/community_versions.json` */
 function getVersionsFilePath(siteDir, pluginId) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONS_JSON_FILE, pluginId));
 }
-exports.getVersionsFilePath = getVersionsFilePath;
 /**
  * Reads the plugin's respective `versions.json` file, and returns its content.
  *
@@ -62,7 +64,6 @@ async function readVersionsFile(siteDir, pluginId) {
     }
     return null;
 }
-exports.readVersionsFile = readVersionsFile;
 /**
  * Reads the `versions.json` file, and returns an ordered list of version names.
  *
@@ -98,7 +99,6 @@ async function readVersionNames(siteDir, options) {
     }
     return versions;
 }
-exports.readVersionNames = readVersionNames;
 /**
  * Gets the path-related version metadata.
  *
@@ -138,4 +138,3 @@ Please set the docs "sidebarPath" field in your config file to:
     }
     return { contentPath, contentPathLocalized, sidebarFilePath };
 }
-exports.getVersionMetadataPaths = getVersionMetadataPaths;

package/lib/versions/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 { FullVersion } from '../types';
 import type { LoadContext } from '@docusaurus/types';
 import type { LoadedVersion, PluginOptions, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';

package/lib/versions/index.js

@@ -6,7 +6,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getVersionFromSourceFilePath = exports.toFullVersion = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionNoIndex = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = void 0;
+exports.getDefaultVersionBanner = getDefaultVersionBanner;
+exports.getVersionBanner = getVersionBanner;
+exports.getVersionBadge = getVersionBadge;
+exports.getVersionNoIndex = getVersionNoIndex;
+exports.filterVersions = filterVersions;
+exports.readVersionsMetadata = readVersionsMetadata;
+exports.toFullVersion = toFullVersion;
+exports.getVersionFromSourceFilePath = getVersionFromSourceFilePath;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
@@ -55,7 +62,6 @@ function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }
     // Older versions: display unmaintained banner
     return 'unmaintained';
 }
-exports.getDefaultVersionBanner = getDefaultVersionBanner;
 function getVersionBanner(context) {
     const { versionName, options } = context;
     const versionBannerOption = options.versions[versionName]?.banner;
@@ -64,7 +70,6 @@ function getVersionBanner(context) {
     }
     return getDefaultVersionBanner(context);
 }
-exports.getVersionBanner = getVersionBanner;
 function getVersionBadge({ versionName, versionNames, options, }) {
     // If site is not versioned or only one version is included
     // we don't show the version badge by default
@@ -72,11 +77,9 @@ function getVersionBadge({ versionName, versionNames, options, }) {
     const defaultVersionBadge = versionNames.length !== 1;
     return options.versions[versionName]?.badge ?? defaultVersionBadge;
 }
-exports.getVersionBadge = getVersionBadge;
 function getVersionNoIndex({ versionName, options, }) {
     return options.versions[versionName]?.noIndex ?? false;
 }
-exports.getVersionNoIndex = getVersionNoIndex;
 function getVersionClassName({ versionName, options, }) {
     const defaultVersionClassName = `docs-version-${versionName}`;
     return options.versions[versionName]?.className ?? defaultVersionClassName;
@@ -138,7 +141,6 @@ function filterVersions(versionNamesUnfiltered, options) {
     }
     return versionNamesUnfiltered;
 }
-exports.filterVersions = filterVersions;
 function getLastVersionName({ versionNames, options, }) {
     return (options.lastVersion ??
         versionNames.find((name) => name !== constants_1.CURRENT_VERSION_NAME) ??
@@ -158,7 +160,6 @@ async function readVersionsMetadata({ context, options, }) {
     })));
     return versionsMetadata;
 }
-exports.readVersionsMetadata = readVersionsMetadata;
 function toFullVersion(version) {
     const sidebarsUtils = (0, utils_2.createSidebarsUtils)(version.sidebars);
     return {
@@ -170,7 +171,6 @@ function toFullVersion(version) {
         }),
     };
 }
-exports.toFullVersion = toFullVersion;
 function getVersionFromSourceFilePath(filePath, versionsMetadata) {
     const versionFound = versionsMetadata.find((version) => (0, utils_1.getContentPathList)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
     if (!versionFound) {
@@ -178,4 +178,3 @@ function getVersionFromSourceFilePath(filePath, versionsMetadata) {
     }
     return versionFound;
 }
-exports.getVersionFromSourceFilePath = getVersionFromSourceFilePath;

package/lib/versions/validation.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 { VersionsOptions } from '@docusaurus/plugin-content-docs';
 export declare function validateVersionName(name: unknown): asserts name is string;
 export declare function validateVersionNames(names: unknown): asserts names is string[];

package/lib/versions/validation.js

@@ -6,7 +6,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateVersionsOptions = exports.validateVersionNames = exports.validateVersionName = void 0;
+exports.validateVersionName = validateVersionName;
+exports.validateVersionNames = validateVersionNames;
+exports.validateVersionsOptions = validateVersionsOptions;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 function validateVersionName(name) {
@@ -29,14 +31,12 @@ function validateVersionName(name) {
         }
     });
 }
-exports.validateVersionName = validateVersionName;
 function validateVersionNames(names) {
     if (!Array.isArray(names)) {
         throw new Error(`The versions file should contain an array of version names! Found content: ${JSON.stringify(names)}`);
     }
     names.forEach(validateVersionName);
 }
-exports.validateVersionNames = validateVersionNames;
 /**
  * @throws Throws for one of the following invalid options:
  * - `lastVersion` is non-existent
@@ -68,4 +68,3 @@ function validateVersionsOptions(availableVersionNames, options) {
         }
     }
 }
-exports.validateVersionsOptions = validateVersionsOptions;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "3.4.0",
+  "version": "3.5.1",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,14 +35,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.4.0",
-    "@docusaurus/logger": "3.4.0",
-    "@docusaurus/mdx-loader": "3.4.0",
-    "@docusaurus/module-type-aliases": "3.4.0",
-    "@docusaurus/types": "3.4.0",
-    "@docusaurus/utils": "3.4.0",
-    "@docusaurus/utils-common": "3.4.0",
-    "@docusaurus/utils-validation": "3.4.0",
+    "@docusaurus/core": "3.5.1",
+    "@docusaurus/logger": "3.5.1",
+    "@docusaurus/mdx-loader": "3.5.1",
+    "@docusaurus/module-type-aliases": "3.5.1",
+    "@docusaurus/theme-common": "3.5.1",
+    "@docusaurus/types": "3.5.1",
+    "@docusaurus/utils": "3.5.1",
+    "@docusaurus/utils-common": "3.5.1",
+    "@docusaurus/utils-validation": "3.5.1",
     "@types/react-router-config": "^5.0.7",
     "combine-promises": "^1.1.0",
     "fs-extra": "^11.1.1",
@@ -66,5 +67,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "49e9a2143274a8dd795659b417b470bc42abbd6e"
+  "gitHead": "5acbc57bd62f3f808ef72007cd67d4c410d13829"
 }

package/src/client/doc.tsx

@@ -0,0 +1,71 @@
+/**
+ * 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 React, {useMemo, type ReactNode, useContext} from 'react';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
+import type {PropDocContent} from '@docusaurus/plugin-content-docs';
+
+/**
+ * The React context value returned by the `useDoc()` hook.
+ * It contains useful data related to the currently browsed doc.
+ */
+export type DocContextValue = Pick<
+  PropDocContent,
+  'metadata' | 'frontMatter' | 'toc' | 'assets' | 'contentTitle'
+>;
+
+const Context = React.createContext<DocContextValue | null>(null);
+
+/**
+ * Note: we don't use `PropDoc` as context value on purpose. Metadata is
+ * currently stored inside the MDX component, but we may want to change that in
+ * the future. This layer is a good opportunity to decouple storage from
+ * consuming API, potentially allowing us to provide metadata as both props and
+ * route context without duplicating the chunks in the future.
+ */
+function useContextValue(content: PropDocContent): DocContextValue {
+  return useMemo(
+    () => ({
+      metadata: content.metadata,
+      frontMatter: content.frontMatter,
+      assets: content.assets,
+      contentTitle: content.contentTitle,
+      toc: content.toc,
+    }),
+    [content],
+  );
+}
+
+/**
+ * This is a very thin layer around the `content` received from the MDX loader.
+ * It provides metadata about the doc to the children tree.
+ */
+export function DocProvider({
+  children,
+  content,
+}: {
+  children: ReactNode;
+  content: PropDocContent;
+}): JSX.Element {
+  const contextValue = useContextValue(content);
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+/**
+ * Returns the data of the currently browsed doc. Gives access to the doc's MDX
+ * Component, front matter, metadata, TOC, etc. When swizzling a low-level
+ * component (e.g. the "Edit this page" link) and you need some extra metadata,
+ * you don't have to drill the props all the way through the component tree:
+ * simply use this hook instead.
+ */
+export function useDoc(): DocContextValue {
+  const doc = useContext(Context);
+  if (doc === null) {
+    throw new ReactContextError('DocProvider');
+  }
+  return doc;
+}