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

package/lib/versions.js

@@ -6,22 +6,19 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDocsDirPaths = exports.readVersionsMetadata = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = void 0;
+exports.getDocsDirPaths = exports.readVersionsMetadata = exports.filterVersions = exports.getVersionBadge = exports.getVersionBanner = exports.getDefaultVersionBanner = exports.readVersionNames = exports.readVersionsFile = exports.getVersionsFilePath = exports.getVersionedSidebarsDirPath = exports.getVersionedDocsDirPath = void 0;
 const tslib_1 = require("tslib");
 const path_1 = (0, tslib_1.__importDefault)(require("path"));
 const fs_extra_1 = (0, tslib_1.__importDefault)(require("fs-extra"));
 const constants_1 = require("./constants");
 const utils_1 = require("@docusaurus/utils");
-const lodash_1 = require("lodash");
+const lodash_1 = (0, tslib_1.__importDefault)(require("lodash"));
 const sidebars_1 = require("./sidebars");
 // retro-compatibility: no prefix for the default plugin id
 function addPluginIdPrefix(fileOrDir, pluginId) {
-    if (pluginId === utils_1.DEFAULT_PLUGIN_ID) {
-        return fileOrDir;
-    }
-    else {
-        return `${pluginId}_${fileOrDir}`;
-    }
+    return pluginId === utils_1.DEFAULT_PLUGIN_ID
+        ? fileOrDir
+        : `${pluginId}_${fileOrDir}`;
 }
 function getVersionedDocsDirPath(siteDir, pluginId) {
     return path_1.default.join(siteDir, addPluginIdPrefix(constants_1.VERSIONED_DOCS_DIR, pluginId));
@@ -57,10 +54,9 @@ async function readVersionsFile(siteDir, pluginId) {
         ensureValidVersionArray(content);
         return content;
     }
-    else {
-        return null;
-    }
+    return null;
 }
+exports.readVersionsFile = readVersionsFile;
 async function readVersionNames(siteDir, options) {
     const versionFileContent = await readVersionsFile(siteDir, options.id);
     if (!versionFileContent && options.disableVersioning) {
@@ -79,6 +75,7 @@ async function readVersionNames(siteDir, options) {
     }
     return versions;
 }
+exports.readVersionNames = readVersionNames;
 function getDocsDirPathLocalized({ siteDir, locale, pluginId, versionName, }) {
     return (0, utils_1.getPluginI18nPath)({
         siteDir,
@@ -149,14 +146,13 @@ function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }
         return null;
     }
     // Upcoming versions: unreleased banner
-    else if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
+    if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
         return 'unreleased';
     }
     // Older versions: display unmaintained banner
-    else {
-        return 'unmaintained';
-    }
+    return 'unmaintained';
 }
+exports.getDefaultVersionBanner = getDefaultVersionBanner;
 function getVersionBanner({ versionName, versionNames, lastVersionName, options, }) {
     var _a;
     const versionBannerOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.banner;
@@ -169,6 +165,7 @@ function getVersionBanner({ versionName, versionNames, lastVersionName, options,
         lastVersionName,
     });
 }
+exports.getVersionBanner = getVersionBanner;
 function getVersionBadge({ versionName, versionNames, options, }) {
     var _a;
     const versionBadgeOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.badge;
@@ -178,6 +175,7 @@ function getVersionBadge({ versionName, versionNames, options, }) {
     const versionBadgeDefault = versionNames.length !== 1;
     return versionBadgeOption !== null && versionBadgeOption !== void 0 ? versionBadgeOption : versionBadgeDefault;
 }
+exports.getVersionBadge = getVersionBadge;
 function getVersionClassName({ versionName, options, }) {
     var _a;
     const versionClassNameOption = (_a = options.versions[versionName]) === null || _a === void 0 ? void 0 : _a.className;
@@ -238,20 +236,21 @@ function createVersionMetadata({ versionName, versionNames, lastVersionName, con
         contentPathLocalized,
     };
 }
-function checkVersionMetadataPaths({ versionMetadata, context, }) {
+async function checkVersionMetadataPaths({ versionMetadata, context, }) {
     const { versionName, contentPath, sidebarFilePath } = versionMetadata;
     const { siteDir } = context;
     const isCurrentVersion = versionName === constants_1.CURRENT_VERSION_NAME;
-    if (!fs_extra_1.default.existsSync(contentPath)) {
+    if (!(await fs_extra_1.default.pathExists(contentPath))) {
         throw new Error(`The docs folder does not exist for version "${versionName}". A docs folder is expected to be found at ${path_1.default.relative(siteDir, contentPath)}.`);
     }
-    // If the current version defines a path to a sidebar file  that does not exist, we throw!
-    // Note: for versioned sidebars, the file may not exist (as we prefer to not create it rather than to create an empty file)
+    // If the current version defines a path to a sidebar file that does not
+    // exist, we throw! Note: for versioned sidebars, the file may not exist (as
+    // we prefer to not create it rather than to create an empty file)
     // See https://github.com/facebook/docusaurus/issues/3366
     // See https://github.com/facebook/docusaurus/pull/4775
     if (isCurrentVersion &&
         typeof sidebarFilePath === 'string' &&
-        !fs_extra_1.default.existsSync(sidebarFilePath)) {
+        !(await fs_extra_1.default.pathExists(sidebarFilePath))) {
         throw new Error(`The path to the sidebar file does not exist at "${path_1.default.relative(siteDir, sidebarFilePath)}".
 Please set the docs "sidebarPath" field in your config file to:
 - a sidebars path that exists
@@ -266,9 +265,7 @@ function getDefaultLastVersionName(versionNames) {
     if (versionNames.length === 1) {
         return versionNames[0];
     }
-    else {
-        return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
-    }
+    return versionNames.filter((versionName) => versionName !== constants_1.CURRENT_VERSION_NAME)[0];
 }
 function checkVersionsOptions(availableVersionNames, options) {
     const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
@@ -276,7 +273,7 @@ function checkVersionsOptions(availableVersionNames, options) {
         !availableVersionNames.includes(options.lastVersion)) {
         throw new Error(`Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
     }
-    const unknownVersionConfigNames = (0, lodash_1.difference)(Object.keys(options.versions), availableVersionNames);
+    const unknownVersionConfigNames = lodash_1.default.difference(Object.keys(options.versions), availableVersionNames);
     if (unknownVersionConfigNames.length > 0) {
         throw new Error(`Invalid docs option "versions": unknown versions (${unknownVersionConfigNames.join(',')}) found. ${availableVersionNamesMsg}`);
     }
@@ -284,7 +281,7 @@ function checkVersionsOptions(availableVersionNames, options) {
         if (options.onlyIncludeVersions.length === 0) {
             throw new Error(`Invalid docs option "onlyIncludeVersions": an empty array is not allowed, at least one version is needed.`);
         }
-        const unknownOnlyIncludeVersionNames = (0, lodash_1.difference)(options.onlyIncludeVersions, availableVersionNames);
+        const unknownOnlyIncludeVersionNames = lodash_1.default.difference(options.onlyIncludeVersions, availableVersionNames);
         if (unknownOnlyIncludeVersionNames.length > 0) {
             throw new Error(`Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(',')}) found. ${availableVersionNamesMsg}`);
         }
@@ -303,10 +300,9 @@ function filterVersions(versionNamesUnfiltered, options) {
     if (options.onlyIncludeVersions) {
         return versionNamesUnfiltered.filter((name) => (options.onlyIncludeVersions || []).includes(name));
     }
-    else {
-        return versionNamesUnfiltered;
-    }
+    return versionNamesUnfiltered;
 }
+exports.filterVersions = filterVersions;
 async function readVersionsMetadata({ context, options, }) {
     var _a;
     const versionNamesUnfiltered = await readVersionNames(context.siteDir, options);
@@ -320,7 +316,7 @@ async function readVersionsMetadata({ context, options, }) {
         context,
         options,
     }));
-    versionsMetadata.forEach((versionMetadata) => checkVersionMetadataPaths({ versionMetadata, context }));
+    await Promise.all(versionsMetadata.map((versionMetadata) => checkVersionMetadataPaths({ versionMetadata, context })));
     return versionsMetadata;
 }
 exports.readVersionsMetadata = readVersionsMetadata;

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@docusaurus/plugin-content-docs",
-  "version": "2.0.0-beta.15",
+  "version": "2.0.0-beta.16",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "exports": {
     "./client": "./lib/client/index.js",
+    "./server": "./lib/server-export.js",
     ".": "./lib/index.js"
   },
   "types": "src/plugin-content-docs.d.ts",
@@ -22,30 +23,30 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "2.0.0-beta.15",
-    "@docusaurus/logger": "2.0.0-beta.15",
-    "@docusaurus/mdx-loader": "2.0.0-beta.15",
-    "@docusaurus/utils": "2.0.0-beta.15",
-    "@docusaurus/utils-validation": "2.0.0-beta.15",
+    "@docusaurus/core": "2.0.0-beta.16",
+    "@docusaurus/logger": "2.0.0-beta.16",
+    "@docusaurus/mdx-loader": "2.0.0-beta.16",
+    "@docusaurus/utils": "2.0.0-beta.16",
+    "@docusaurus/utils-validation": "2.0.0-beta.16",
     "combine-promises": "^1.1.0",
-    "fs-extra": "^10.0.0",
-    "import-fresh": "^3.2.2",
-    "js-yaml": "^4.0.0",
-    "lodash": "^4.17.20",
+    "fs-extra": "^10.0.1",
+    "import-fresh": "^3.3.0",
+    "js-yaml": "^4.1.0",
+    "lodash": "^4.17.21",
     "remark-admonitions": "^1.2.1",
-    "shelljs": "^0.8.4",
     "tslib": "^2.3.1",
     "utility-types": "^3.10.0",
-    "webpack": "^5.61.0"
+    "webpack": "^5.69.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "2.0.0-beta.15",
-    "@docusaurus/types": "2.0.0-beta.15",
-    "@types/js-yaml": "^4.0.0",
-    "@types/picomatch": "^2.2.1",
+    "@docusaurus/module-type-aliases": "2.0.0-beta.16",
+    "@docusaurus/types": "2.0.0-beta.16",
+    "@types/js-yaml": "^4.0.5",
+    "@types/picomatch": "^2.3.0",
     "commander": "^5.1.0",
     "escape-string-regexp": "^4.0.0",
-    "picomatch": "^2.1.1",
+    "picomatch": "^2.3.1",
+    "shelljs": "^0.8.5",
     "utility-types": "^3.10.0"
   },
   "peerDependencies": {
@@ -55,5 +56,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "6cfad16436c07d8d11e5c2e1486dc59afd483e33"
+  "gitHead": "eb43c4d4f95a4fb97dc9bb9dc615413e0dc2e1e7"
 }

package/src/cli.ts

@@ -16,11 +16,11 @@ import type {
   PathOptions,
   SidebarOptions,
 } from '@docusaurus/plugin-content-docs';
-import {loadSidebarsFile, resolveSidebarPathOption} from './sidebars';
+import {loadSidebarsFileUnsafe, resolveSidebarPathOption} from './sidebars';
 import {DEFAULT_PLUGIN_ID} from '@docusaurus/utils';
 import logger from '@docusaurus/logger';
 
-function createVersionedSidebarFile({
+async function createVersionedSidebarFile({
   siteDir,
   pluginId,
   sidebarPath,
@@ -32,10 +32,13 @@ function createVersionedSidebarFile({
   version: string;
 }) {
   // Load current sidebar and create a new versioned sidebars file (if needed).
-  // Note: we don't need the sidebars file to be normalized: it's ok to let plugin option changes to impact older, versioned sidebars
-  const sidebars = loadSidebarsFile(sidebarPath);
+  // Note: we don't need the sidebars file to be normalized: it's ok to let
+  // plugin option changes to impact older, versioned sidebars
+  // We don't validate here, assuming the user has already built the version
+  const sidebars = await loadSidebarsFileUnsafe(sidebarPath);
 
-  // Do not create a useless versioned sidebars file if sidebars file is empty or sidebars are disabled/false)
+  // Do not create a useless versioned sidebars file if sidebars file is empty
+  // or sidebars are disabled/false)
   const shouldCreateVersionedSidebarFile = Object.keys(sidebars).length > 0;
 
   if (shouldCreateVersionedSidebarFile) {
@@ -44,8 +47,8 @@ function createVersionedSidebarFile({
       versionedSidebarsDir,
       `version-${version}-sidebars.json`,
     );
-    fs.ensureDirSync(path.dirname(newSidebarFile));
-    fs.writeFileSync(
+    await fs.ensureDir(path.dirname(newSidebarFile));
+    await fs.writeFile(
       newSidebarFile,
       `${JSON.stringify(sidebars, null, 2)}\n`,
       'utf8',
@@ -54,12 +57,12 @@ function createVersionedSidebarFile({
 }
 
 // Tests depend on non-default export for mocking.
-export function cliDocsVersionCommand(
+export async function cliDocsVersionCommand(
   version: string | null | undefined,
   siteDir: string,
   pluginId: string,
   options: PathOptions & SidebarOptions,
-): void {
+): Promise<void> {
   // It wouldn't be very user-friendly to show a [default] log prefix,
   // so we use [docs] instead of [default]
   const pluginIdLogPrefix =
@@ -101,8 +104,8 @@ export function cliDocsVersionCommand(
   // Load existing versions.
   let versions = [];
   const versionsJSONFile = getVersionsFilePath(siteDir, pluginId);
-  if (fs.existsSync(versionsJSONFile)) {
-    versions = JSON.parse(fs.readFileSync(versionsJSONFile, 'utf8'));
+  if (await fs.pathExists(versionsJSONFile)) {
+    versions = JSON.parse(await fs.readFile(versionsJSONFile, 'utf8'));
   }
 
   // Check if version already exists.
@@ -117,15 +120,18 @@ export function cliDocsVersionCommand(
   // Copy docs files.
   const docsDir = path.join(siteDir, docsPath);
 
-  if (fs.existsSync(docsDir) && fs.readdirSync(docsDir).length > 0) {
+  if (
+    (await fs.pathExists(docsDir)) &&
+    (await fs.readdir(docsDir)).length > 0
+  ) {
     const versionedDir = getVersionedDocsDirPath(siteDir, pluginId);
     const newVersionDir = path.join(versionedDir, `version-${version}`);
-    fs.copySync(docsDir, newVersionDir);
+    await fs.copy(docsDir, newVersionDir);
   } else {
     throw new Error(`${pluginIdLogPrefix}: there is no docs to version!`);
   }
 
-  createVersionedSidebarFile({
+  await createVersionedSidebarFile({
     siteDir,
     pluginId,
     version,
@@ -134,8 +140,11 @@ export function cliDocsVersionCommand(
 
   // Update versions.json file.
   versions.unshift(version);
-  fs.ensureDirSync(path.dirname(versionsJSONFile));
-  fs.writeFileSync(versionsJSONFile, `${JSON.stringify(versions, null, 2)}\n`);
+  await fs.ensureDir(path.dirname(versionsJSONFile));
+  await fs.writeFile(
+    versionsJSONFile,
+    `${JSON.stringify(versions, null, 2)}\n`,
+  );
 
   logger.success`name=${pluginIdLogPrefix}: version name=${version} created!`;
 }

package/src/client/docsClientUtils.ts

@@ -28,7 +28,7 @@ export function getActivePlugin(
   options: GetActivePluginOptions = {},
 ): ActivePlugin | undefined {
   const activeEntry = Object.entries(allPluginDatas)
-    // A quick route sorting: '/android/foo' should match '/android' instead of '/'
+    // Route sorting: '/android/foo' should match '/android' instead of '/'
     .sort((a, b) => b[1].path.localeCompare(a[1].path))
     .find(
       ([, pluginData]) =>
@@ -67,7 +67,7 @@ export const getActiveVersion = (
 ): GlobalVersion | undefined => {
   const lastVersion = getLatestVersion(data);
   // Last version is a route like /docs/*,
-  // we need to try to match it last or it would match /docs/version-1.0/* as well
+  // we need to match it last or it would match /docs/version-1.0/* as well
   const orderedVersionsMetadata = [
     ...data.versions.filter((version) => version !== lastVersion),
     lastVersion,

package/src/client/index.ts

@@ -5,4 +5,100 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-export * from './globalDataHooks';
+import {useLocation} from '@docusaurus/router';
+import useGlobalData, {usePluginData} from '@docusaurus/useGlobalData';
+
+import {
+  getActivePlugin,
+  getLatestVersion,
+  getActiveVersion,
+  getActiveDocContext,
+  getDocVersionSuggestions,
+} from './docsClientUtils';
+import type {
+  GlobalPluginData,
+  GlobalVersion,
+  ActivePlugin,
+  ActiveDocContext,
+  DocVersionSuggestions,
+  GetActivePluginOptions,
+} from '@docusaurus/plugin-content-docs/client';
+
+// Important to use a constant object to avoid React useEffect executions etc.
+// see https://github.com/facebook/docusaurus/issues/5089
+const StableEmptyObject = {};
+
+// Not using useAllPluginInstancesData() because in blog-only mode, docs hooks
+// are still used by the theme. We need a fail-safe fallback when the docs
+// plugin is not in use
+export const useAllDocsData = (): Record<string, GlobalPluginData> =>
+  useGlobalData()['docusaurus-plugin-content-docs'] ?? StableEmptyObject;
+
+export const useDocsData = (pluginId: string | undefined): GlobalPluginData =>
+  usePluginData('docusaurus-plugin-content-docs', pluginId) as GlobalPluginData;
+
+// TODO this feature should be provided by docusaurus core
+export const useActivePlugin = (
+  options: GetActivePluginOptions = {},
+): ActivePlugin | undefined => {
+  const data = useAllDocsData();
+  const {pathname} = useLocation();
+  return getActivePlugin(data, pathname, options);
+};
+
+export const useActivePluginAndVersion = (
+  options: GetActivePluginOptions = {},
+):
+  | undefined
+  | {activePlugin: ActivePlugin; activeVersion: GlobalVersion | undefined} => {
+  const activePlugin = useActivePlugin(options);
+  const {pathname} = useLocation();
+  if (activePlugin) {
+    const activeVersion = getActiveVersion(activePlugin.pluginData, pathname);
+    return {
+      activePlugin,
+      activeVersion,
+    };
+  }
+  return undefined;
+};
+
+// versions are returned ordered (most recent first)
+export const useVersions = (pluginId: string | undefined): GlobalVersion[] => {
+  const data = useDocsData(pluginId);
+  return data.versions;
+};
+
+export const useLatestVersion = (
+  pluginId: string | undefined,
+): GlobalVersion => {
+  const data = useDocsData(pluginId);
+  return getLatestVersion(data);
+};
+
+// Note: return undefined on doc-unrelated pages,
+// because there's no version currently considered as active
+export const useActiveVersion = (
+  pluginId: string | undefined,
+): GlobalVersion | undefined => {
+  const data = useDocsData(pluginId);
+  const {pathname} = useLocation();
+  return getActiveVersion(data, pathname);
+};
+
+export const useActiveDocContext = (
+  pluginId: string | undefined,
+): ActiveDocContext => {
+  const data = useDocsData(pluginId);
+  const {pathname} = useLocation();
+  return getActiveDocContext(data, pathname);
+};
+
+// Useful to say "hey, you are not on the latest docs version, please switch"
+export const useDocVersionSuggestions = (
+  pluginId: string | undefined,
+): DocVersionSuggestions => {
+  const data = useDocsData(pluginId);
+  const {pathname} = useLocation();
+  return getDocVersionSuggestions(data, pathname);
+};

package/src/docFrontMatter.ts

@@ -30,6 +30,7 @@ const DocFrontMatterSchema = Joi.object<DocFrontMatter>({
   sidebar_label: Joi.string(),
   sidebar_position: Joi.number(),
   sidebar_class_name: Joi.string(),
+  sidebar_custom_props: Joi.object().unknown(),
   displayed_sidebar: Joi.string().allow(null),
   tags: FrontMatterTagsSchema,
   pagination_label: Joi.string(),

package/src/docs.ts

@@ -8,7 +8,6 @@
 import path from 'path';
 import fs from 'fs-extra';
 import logger from '@docusaurus/logger';
-import {keyBy} from 'lodash';
 import {
   aliasedSitePath,
   getEditUrl,
@@ -139,7 +138,8 @@ function doProcessDocMetadata({
   const {
     custom_edit_url: customEditURL,
 
-    // Strip number prefixes by default (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc) by default,
+    // Strip number prefixes by default
+    // (01-MyFolder/01-MyDoc.md => MyFolder/MyDoc)
     // but allow to disable this behavior with front matter
     parse_number_prefixes: parseNumberPrefixes = true,
   } = frontMatter;
@@ -164,7 +164,8 @@ function doProcessDocMetadata({
     throw new Error(`Document id "${baseID}" cannot include slash.`);
   }
 
-  // For autogenerated sidebars, sidebar position can come from filename number prefix or front matter
+  // For autogenerated sidebars, sidebar position can come from filename number
+  // prefix or front matter
   const sidebarPosition: number | undefined =
     frontMatter.sidebar_position ?? numberPrefix;
 
@@ -205,8 +206,9 @@ function doProcessDocMetadata({
     numberPrefixParser: options.numberPrefixParser,
   });
 
-  // Note: the title is used by default for page title, sidebar label, pagination buttons...
-  // frontMatter.title should be used in priority over contentTitle (because it can contain markdown/JSX syntax)
+  // Note: the title is used by default for page title, sidebar label,
+  // pagination buttons... frontMatter.title should be used in priority over
+  // contentTitle (because it can contain markdown/JSX syntax)
   const title: string = frontMatter.title ?? contentTitle ?? baseID;
 
   const description: string = frontMatter.description ?? excerpt ?? '';
@@ -233,9 +235,8 @@ function doProcessDocMetadata({
           ? versionMetadata.versionEditUrlLocalized
           : versionMetadata.versionEditUrl;
       return getEditUrl(relativeFilePath, baseVersionEditUrl);
-    } else {
-      return undefined;
     }
+    return undefined;
   }
 
   // Assign all of object properties during instantiation (if possible) for
@@ -274,9 +275,9 @@ export function processDocMetadata(args: {
 }): DocMetadataBase {
   try {
     return doProcessDocMetadata(args);
-  } catch (e) {
+  } catch (err) {
     logger.error`Can't process doc metadata for doc at path path=${args.docFile.filePath} in version name=${args.versionMetadata.versionName}`;
-    throw e;
+    throw err;
   }
 }
 
@@ -361,9 +362,8 @@ export function getMainDocId({
           doc.id === firstDocIdOfFirstSidebar ||
           doc.unversionedId === firstDocIdOfFirstSidebar,
       )!;
-    } else {
-      return docs[0];
     }
+    return docs[0];
   }
 
   return getMainDoc().unversionedId;
@@ -407,7 +407,8 @@ export function toCategoryIndexMatcherParam({
 }
 
 /**
- * guides/sidebar/autogenerated.md -> 'autogenerated', '.md', ['sidebar', 'guides']
+ * `guides/sidebar/autogenerated.md` ->
+ *   `'autogenerated', '.md', ['sidebar', 'guides']`
  */
 export function splitPath(str: string): {
   /**
@@ -428,20 +429,24 @@ export function splitPath(str: string): {
 }
 
 // Return both doc ids
-// TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
-// ("id" should be removed & "versionedId" should be renamed to "id")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 export function getDocIds(doc: DocMetadataBase): [string, string] {
   return [doc.unversionedId, doc.id];
 }
 
 // docs are indexed by both versioned and unversioned ids at the same time
-// TODO legacy retro-compatibility due to old versioned sidebars using versioned doc ids
-// ("id" should be removed & "versionedId" should be renamed to "id")
+// TODO legacy retro-compatibility due to old versioned sidebars using
+// versioned doc ids ("id" should be removed & "versionedId" should be renamed
+// to "id")
 export function createDocsByIdIndex<
   Doc extends {id: string; unversionedId: string},
 >(docs: Doc[]): Record<string, Doc> {
-  return {
-    ...keyBy(docs, (doc) => doc.unversionedId),
-    ...keyBy(docs, (doc) => doc.id),
-  };
+  return Object.fromEntries(
+    docs.flatMap((doc) => [
+      [doc.unversionedId, doc],
+      [doc.id, doc],
+    ]),
+  );
 }

package/src/globalData.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {mapValues} from 'lodash';
+import _ from 'lodash';
 import {normalizeUrl} from '@docusaurus/utils';
 import type {Sidebars} from './sidebars/types';
 import {createSidebarsUtils} from './sidebars/utils';
@@ -43,7 +43,7 @@ export function toGlobalSidebars(
   version: LoadedVersion,
 ): Record<string, GlobalSidebar> {
   const {getFirstLink} = createSidebarsUtils(sidebars);
-  return mapValues(sidebars, (sidebar, sidebarId) => {
+  return _.mapValues(sidebars, (sidebar, sidebarId) => {
     const firstLink = getFirstLink(sidebarId);
     if (!firstLink) {
       return {};

package/src/index.ts

@@ -38,11 +38,11 @@ import type {
   DocFile,
   DocsMarkdownOption,
   VersionTag,
+  DocFrontMatter,
 } from './types';
 import type {RuleSetRule} from 'webpack';
 import {cliDocsVersionCommand} from './cli';
 import {VERSIONS_JSON_FILE} from './constants';
-import {keyBy, mapValues} from 'lodash';
 import {toGlobalDataVersion} from './globalData';
 import {toTagDocListProp} from './props';
 import {
@@ -196,9 +196,9 @@ export default async function pluginContentDocs(
       async function loadVersion(versionMetadata: VersionMetadata) {
         try {
           return await doLoadVersion(versionMetadata);
-        } catch (e) {
+        } catch (err) {
           logger.error`Loading of version failed for version name=${versionMetadata.versionName}`;
-          throw e;
+          throw err;
         }
       }
 
@@ -217,6 +217,7 @@ export default async function pluginContentDocs(
         docLayoutComponent,
         docItemComponent,
         docCategoryGeneratedIndexComponent,
+        breadcrumbs,
       } = options;
       const {addRoute, createData, setGlobalData} = actions;
 
@@ -295,6 +296,7 @@ export default async function pluginContentDocs(
       setGlobalData<GlobalPluginData>({
         path: normalizeUrl([baseUrl, options.routeBasePath]),
         versions: loadedVersions.map(toGlobalDataVersion),
+        breadcrumbs,
       });
     },
 
@@ -309,9 +311,8 @@ export default async function pluginContentDocs(
 
       function getSourceToPermalink(): SourceToPermalink {
         const allDocs = content.loadedVersions.flatMap((v) => v.docs);
-        return mapValues(
-          keyBy(allDocs, (d) => d.source),
-          (d) => d.permalink,
+        return Object.fromEntries(
+          allDocs.map(({source, permalink}) => [source, permalink]),
         );
       }
 
@@ -333,7 +334,7 @@ export default async function pluginContentDocs(
       function createMDXLoaderRule(): RuleSetRule {
         const contentDirs = versionsMetadata.flatMap(getDocsDirPaths);
         return {
-          test: /(\.mdx?)$/,
+          test: /\.mdx?$/i,
           include: contentDirs
             // Trailing slash is important, see https://github.com/facebook/docusaurus/pull/3970
             .map(addTrailingPathSeparator),
@@ -360,6 +361,15 @@ export default async function pluginContentDocs(
                   const aliasedPath = aliasedSitePath(mdxPath, siteDir);
                   return path.join(dataDir, `${docuHash(aliasedPath)}.json`);
                 },
+                // Assets allow to convert some relative images paths to
+                // require(...) calls
+                createAssets: ({
+                  frontMatter,
+                }: {
+                  frontMatter: DocFrontMatter;
+                }) => ({
+                  image: frontMatter.image,
+                }),
               },
             },
             {