@azerion/bunosaurus-plugin-content-docs 0.0.0-stage → 4.0.0

package/lib/versions/validation.js

@@ -0,0 +1,70 @@
+"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.validateVersionName = validateVersionName;
+exports.validateVersionNames = validateVersionNames;
+exports.validateVersionsOptions = validateVersionsOptions;
+const tslib_1 = require("tslib");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
+function validateVersionName(name) {
+    if (typeof name !== 'string') {
+        throw new Error(`Versions should be strings. Found type "${typeof name}" for version ${JSON.stringify(name)}.`);
+    }
+    if (!name.trim()) {
+        throw new Error(`Invalid version name "${name}": version name must contain at least one non-whitespace character.`);
+    }
+    const errors = [
+        [/[/\\]/, 'should not include slash (/) or backslash (\\)'],
+        [/.{33,}/, 'cannot be longer than 32 characters'],
+        // eslint-disable-next-line no-control-regex
+        [/[<>:"|?*\x00-\x1F]/, 'should be a valid file path'],
+        [/^\.\.?$/, 'should not be "." or ".."'],
+    ];
+    errors.forEach(([pattern, message]) => {
+        if (pattern.test(name)) {
+            throw new Error(`Invalid version name "${name}": version name ${message}.`);
+        }
+    });
+}
+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);
+}
+/**
+ * @throws Throws for one of the following invalid options:
+ * - `lastVersion` is non-existent
+ * - `versions` includes unknown keys
+ * - `onlyIncludeVersions` is empty, contains unknown names, or doesn't include
+ * `latestVersion` (if provided)
+ */
+function validateVersionsOptions(availableVersionNames, options) {
+    const availableVersionNamesMsg = `Available version names are: ${availableVersionNames.join(', ')}`;
+    if (options.lastVersion &&
+        !availableVersionNames.includes(options.lastVersion)) {
+        throw new Error(`Docs option lastVersion: ${options.lastVersion} is invalid. ${availableVersionNamesMsg}`);
+    }
+    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}`);
+    }
+    if (options.onlyIncludeVersions) {
+        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 = lodash_1.default.difference(options.onlyIncludeVersions, availableVersionNames);
+        if (unknownOnlyIncludeVersionNames.length > 0) {
+            throw new Error(`Invalid docs option "onlyIncludeVersions": unknown versions (${unknownOnlyIncludeVersionNames.join(',')}) found. ${availableVersionNamesMsg}`);
+        }
+        if (options.lastVersion &&
+            !options.onlyIncludeVersions.includes(options.lastVersion)) {
+            throw new Error(`Invalid docs option "lastVersion": if you use both the "onlyIncludeVersions" and "lastVersion" options, then "lastVersion" must be present in the provided "onlyIncludeVersions" array.`);
+        }
+    }
+}

package/lib/versions/version.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { FullVersion } from '../types';
+import type { LoadContext } from '@docusaurus/types';
+import type { LoadedVersion, PluginOptions, VersionBanner, VersionMetadata } from '@docusaurus/plugin-content-docs';
+export type VersionContext = {
+    /** The version name to get banner of. */
+    versionName: string;
+    /** All versions, ordered from newest to oldest. */
+    versionNames: string[];
+    lastVersionName: string;
+    context: LoadContext;
+    options: PluginOptions;
+};
+/**
+ * The default version banner depends on the version's relative position to the
+ * latest version. More recent ones are "unreleased", and older ones are
+ * "unmaintained".
+ */
+export declare function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }: VersionContext): VersionBanner | null;
+export declare function getVersionBanner(context: VersionContext): VersionMetadata['banner'];
+export declare function getVersionBadge({ versionName, versionNames, options, }: VersionContext): VersionMetadata['badge'];
+export declare function getVersionNoIndex({ versionName, options, }: VersionContext): VersionMetadata['noIndex'];
+/**
+ * Filter versions according to provided options (i.e. `onlyIncludeVersions`).
+ *
+ * Note: we preserve the order in which versions are provided; the order of the
+ * `onlyIncludeVersions` array does not matter
+ */
+export declare function filterVersions(versionNamesUnfiltered: string[], options: PluginOptions): string[];
+export declare function readVersionsMetadata({ context, options, }: {
+    context: LoadContext;
+    options: PluginOptions;
+}): Promise<VersionMetadata[]>;
+export declare function toFullVersion(version: LoadedVersion): FullVersion;
+export declare function getVersionFromSourceFilePath(filePath: string, versionsMetadata: VersionMetadata[]): VersionMetadata;

package/lib/versions/version.js

@@ -0,0 +1,189 @@
+"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.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 node_path_1 = tslib_1.__importDefault(require("node:path"));
+const utils_1 = require("@docusaurus/utils");
+const constants_1 = require("../constants");
+const validation_1 = require("./validation");
+const files_1 = require("./files");
+const utils_2 = require("../sidebars/utils");
+const categoryGeneratedIndex_1 = require("../categoryGeneratedIndex");
+function getVersionEditUrls({ contentPath, contentPathLocalized, context, options, }) {
+    // If the user is using the functional form of editUrl,
+    // she has total freedom and we can't compute a "version edit url"
+    if (!options.editUrl || typeof options.editUrl === 'function') {
+        return { editUrl: undefined, editUrlLocalized: undefined };
+    }
+    // Intermediate var just to please TS not narrowing to "string"
+    const editUrlOption = options.editUrl;
+    const getEditUrl = () => {
+        const editDirPath = options.editCurrentVersion ? options.path : contentPath;
+        return (0, utils_1.normalizeUrl)([
+            editUrlOption,
+            (0, utils_1.posixPath)(node_path_1.default.relative(context.siteDir, node_path_1.default.resolve(context.siteDir, editDirPath))),
+        ]);
+    };
+    const getEditUrlLocalized = () => {
+        if (!contentPathLocalized) {
+            return undefined;
+        }
+        const editDirPathLocalized = options.editCurrentVersion
+            ? (0, files_1.getDocsDirPathLocalized)({
+                localizationDir: context.localizationDir,
+                versionName: constants_1.CURRENT_VERSION_NAME,
+                pluginId: options.id,
+            })
+            : contentPathLocalized;
+        return (0, utils_1.normalizeUrl)([
+            editUrlOption,
+            (0, utils_1.posixPath)(node_path_1.default.relative(context.siteDir, node_path_1.default.resolve(context.siteDir, editDirPathLocalized))),
+        ]);
+    };
+    return { editUrl: getEditUrl(), editUrlLocalized: getEditUrlLocalized() };
+}
+/**
+ * The default version banner depends on the version's relative position to the
+ * latest version. More recent ones are "unreleased", and older ones are
+ * "unmaintained".
+ */
+function getDefaultVersionBanner({ versionName, versionNames, lastVersionName, }) {
+    // Current version: good, no banner
+    if (versionName === lastVersionName) {
+        return null;
+    }
+    // Upcoming versions: unreleased banner
+    if (versionNames.indexOf(versionName) < versionNames.indexOf(lastVersionName)) {
+        return 'unreleased';
+    }
+    // Older versions: display unmaintained banner
+    return 'unmaintained';
+}
+function getVersionBanner(context) {
+    const { versionName, options } = context;
+    const versionBannerOption = options.versions[versionName]?.banner;
+    if (versionBannerOption) {
+        return versionBannerOption === 'none' ? null : versionBannerOption;
+    }
+    return getDefaultVersionBanner(context);
+}
+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
+    // See https://github.com/facebook/docusaurus/issues/3362
+    const defaultVersionBadge = versionNames.length !== 1;
+    return options.versions[versionName]?.badge ?? defaultVersionBadge;
+}
+function getVersionNoIndex({ versionName, options, }) {
+    return options.versions[versionName]?.noIndex ?? false;
+}
+function getVersionClassName({ versionName, options, }) {
+    const defaultVersionClassName = `docs-version-${versionName}`;
+    return options.versions[versionName]?.className ?? defaultVersionClassName;
+}
+function getVersionLabel({ versionName, options, }) {
+    const defaultVersionLabel = versionName === constants_1.CURRENT_VERSION_NAME ? 'Next' : versionName;
+    return options.versions[versionName]?.label ?? defaultVersionLabel;
+}
+function getVersionPathPart({ versionName, options, lastVersionName, }) {
+    function getDefaultVersionPathPart() {
+        if (versionName === lastVersionName) {
+            return '';
+        }
+        return versionName === constants_1.CURRENT_VERSION_NAME ? 'next' : versionName;
+    }
+    return options.versions[versionName]?.path ?? getDefaultVersionPathPart();
+}
+async function createVersionMetadata(context) {
+    const { versionName, lastVersionName, options, context: loadContext } = context;
+    const { sidebarFilePath, contentPath, contentPathLocalized } = await (0, files_1.getVersionMetadataPaths)(context);
+    const versionPathPart = getVersionPathPart(context);
+    const routePath = (0, utils_1.normalizeUrl)([
+        loadContext.baseUrl,
+        options.routeBasePath,
+        versionPathPart,
+    ]);
+    const versionEditUrls = getVersionEditUrls({
+        contentPath,
+        contentPathLocalized,
+        context: loadContext,
+        options,
+    });
+    return {
+        versionName,
+        label: getVersionLabel(context),
+        banner: getVersionBanner(context),
+        badge: getVersionBadge(context),
+        noIndex: getVersionNoIndex(context),
+        className: getVersionClassName(context),
+        path: routePath,
+        tagsPath: (0, utils_1.normalizeUrl)([routePath, options.tagsBasePath]),
+        ...versionEditUrls,
+        isLast: versionName === lastVersionName,
+        routePriority: versionPathPart === '' ? -1 : undefined,
+        sidebarFilePath,
+        contentPath,
+        contentPathLocalized,
+    };
+}
+/**
+ * Filter versions according to provided options (i.e. `onlyIncludeVersions`).
+ *
+ * Note: we preserve the order in which versions are provided; the order of the
+ * `onlyIncludeVersions` array does not matter
+ */
+function filterVersions(versionNamesUnfiltered, options) {
+    if (options.onlyIncludeVersions) {
+        return versionNamesUnfiltered.filter((name) => options.onlyIncludeVersions.includes(name));
+    }
+    return versionNamesUnfiltered;
+}
+function getLastVersionName({ versionNames, options, }) {
+    return (options.lastVersion ??
+        versionNames.find((name) => name !== constants_1.CURRENT_VERSION_NAME) ??
+        constants_1.CURRENT_VERSION_NAME);
+}
+async function readVersionsMetadata({ context, options, }) {
+    const allVersionNames = await (0, files_1.readVersionNames)(context.siteDir, options);
+    (0, validation_1.validateVersionsOptions)(allVersionNames, options);
+    const versionNames = filterVersions(allVersionNames, options);
+    const lastVersionName = getLastVersionName({ versionNames, options });
+    return Promise.all(versionNames.map((versionName) => createVersionMetadata({
+        versionName,
+        versionNames,
+        lastVersionName,
+        context,
+        options,
+    })));
+}
+function toFullVersion(version) {
+    const sidebarsUtils = (0, utils_2.createSidebarsUtils)(version.sidebars);
+    return {
+        ...version,
+        sidebarsUtils,
+        categoryGeneratedIndices: (0, categoryGeneratedIndex_1.getCategoryGeneratedIndexMetadataList)({
+            docs: version.docs,
+            sidebarsUtils,
+        }),
+    };
+}
+function getVersionFromSourceFilePath(filePath, versionsMetadata) {
+    const versionFound = versionsMetadata.find((version) => (0, utils_1.getContentPathList)(version).some((docsDirPath) => filePath.startsWith(docsDirPath)));
+    if (!versionFound) {
+        throw new Error(`Unexpected error: file at "${filePath}" does not belong to any docs version!`);
+    }
+    return versionFound;
+}

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@azerion/bunosaurus-plugin-content-docs",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "Docs plugin for Docusaurus.",
+  "main": "lib/index.js",
+  "sideEffects": false,
+  "exports": {
+    "./lib/*": "./lib/*",
+    "./src/*": "./src/*",
+    "./client": {
+      "type": "./lib/client/index.d.ts",
+      "default": "./lib/client/index.js"
+    },
+    "./server": {
+      "type": "./lib/server-export.d.ts",
+      "default": "./lib/server-export.js"
+    },
+    ".": {
+      "types": "./src/plugin-content-docs.d.ts",
+      "default": "./lib/index.js"
+    }
+  },
+  "types": "src/plugin-content-docs.d.ts",
+  "scripts": {
+    "build": "tsc --build",
+    "watch": "tsc --build --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-plugin-content-docs"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@docusaurus/core": "npm:@azerion/bunosaurus-core@4.0.0",
+    "@docusaurus/fs": "npm:@azerion/bunosaurus-fs@4.0.0",
+    "@docusaurus/glob": "npm:@azerion/bunosaurus-glob@4.0.0",
+    "@docusaurus/logger": "npm:@azerion/bunosaurus-logger@4.0.0",
+    "@docusaurus/mdx-loader": "npm:@azerion/bunosaurus-mdx-loader@4.0.0",
+    "@docusaurus/module-type-aliases": "npm:@azerion/bunosaurus-module-type-aliases@4.0.0",
+    "@docusaurus/theme-common": "npm:@azerion/bunosaurus-theme-common@4.0.0",
+    "@docusaurus/types": "npm:@azerion/bunosaurus-types@4.0.0",
+    "@docusaurus/utils": "npm:@azerion/bunosaurus-utils@4.0.0",
+    "@docusaurus/utils-common": "npm:@azerion/bunosaurus-utils-common@4.0.0",
+    "@docusaurus/utils-validation": "npm:@azerion/bunosaurus-utils-validation@4.0.0",
+    "@types/react-router-config": "^5.0.11",
+    "combine-promises": "^1.2.0",
+    "js-yaml": "^5.4.1",
+    "lodash": "^4.18.1",
+    "schema-dts": "^1.1.5",
+    "tslib": "^2.8.1",
+    "utility-types": "^3.11.0"
+  },
+  "devDependencies": {
+    "@total-typescript/shoehorn": "^0.1.2",
+    "@types/picomatch": "^2.3.4",
+    "commander": "^15.0.0",
+    "picomatch": "^2.3.2",
+    "react-router-dom": "^5.3.4",
+    "webpack": "^5.111.0"
+  },
+  "peerDependencies": {
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  }
+}

package/src/categoryGeneratedIndex.ts

@@ -0,0 +1,60 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import {type SidebarsUtils, toNavigationLink} from './sidebars/utils';
+import {createDocsByIdIndex} from './docs';
+import type {
+  CategoryGeneratedIndexMetadata,
+  DocMetadataBase,
+} from '@docusaurus/plugin-content-docs';
+import type {SidebarItemCategoryWithGeneratedIndex} from './sidebars/types';
+
+function getCategoryGeneratedIndexMetadata({
+  category,
+  sidebarsUtils,
+  docsById,
+}: {
+  category: SidebarItemCategoryWithGeneratedIndex;
+  sidebarsUtils: SidebarsUtils;
+  docsById: {[docId: string]: DocMetadataBase};
+}): CategoryGeneratedIndexMetadata {
+  const {sidebarName, previous, next} =
+    sidebarsUtils.getCategoryGeneratedIndexNavigation(category.link.permalink);
+  return {
+    title: category.link.title ?? category.label,
+    description: category.link.description,
+    image: category.link.image,
+    keywords: category.link.keywords,
+    slug: category.link.slug,
+    permalink: category.link.permalink,
+    sidebar: sidebarName!,
+    navigation: {
+      previous: toNavigationLink(previous, docsById),
+      next: toNavigationLink(next, docsById),
+    },
+  };
+}
+
+export function getCategoryGeneratedIndexMetadataList({
+  docs,
+  sidebarsUtils,
+}: {
+  sidebarsUtils: SidebarsUtils;
+  docs: DocMetadataBase[];
+}): CategoryGeneratedIndexMetadata[] {
+  const docsById = createDocsByIdIndex(docs);
+
+  const categoryGeneratedIndexItems =
+    sidebarsUtils.getCategoryGeneratedIndexList();
+  return categoryGeneratedIndexItems.map((category) =>
+    getCategoryGeneratedIndexMetadata({
+      category,
+      sidebarsUtils,
+      docsById,
+    }),
+  );
+}

package/src/cli.ts

@@ -0,0 +1,180 @@
+/**
+ * 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 path from 'node:path';
+import logger from '@docusaurus/logger';
+import {DEFAULT_PLUGIN_ID, getLocaleConfig} from '@docusaurus/utils';
+import {fs, pathExists, outputFile} from '@docusaurus/fs';
+import {
+  getVersionsFilePath,
+  getVersionDocsDirPath,
+  getVersionSidebarsPath,
+  getDocsDirPathLocalized,
+  getPluginDirPathLocalized,
+  readVersionsFile,
+} from './versions/files';
+import {validateVersionName} from './versions/validation';
+import {loadSidebarsFile} from './sidebars';
+import {CURRENT_VERSION_NAME} from './constants';
+import type {PluginOptions} from '@docusaurus/plugin-content-docs';
+import type {LoadContext} from '@docusaurus/types';
+
+async function createVersionedSidebarFile({
+  siteDir,
+  pluginId,
+  sidebarPath,
+  version,
+}: {
+  siteDir: string;
+  pluginId: string;
+  sidebarPath: string | false | undefined;
+  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
+  // We don't validate here, assuming the user has already built the version
+  const sidebars = await loadSidebarsFile(sidebarPath);
+
+  // 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) {
+    await outputFile(
+      getVersionSidebarsPath(siteDir, pluginId, version),
+      `${JSON.stringify(sidebars, null, 2)}\n`,
+      'utf8',
+    );
+  }
+}
+
+// Tests depend on non-default export for mocking.
+async function cliDocsVersionCommand(
+  version: unknown,
+  {id: pluginId, path: docsPath, sidebarPath}: PluginOptions,
+  {siteDir, i18n}: LoadContext,
+): Promise<void> {
+  // It wouldn't be very user-friendly to show a [default] log prefix,
+  // so we use [docs] instead of [default]
+  const pluginIdLogPrefix =
+    pluginId === DEFAULT_PLUGIN_ID ? '[docs]' : `[${pluginId}]`;
+
+  try {
+    validateVersionName(version);
+  } catch (err) {
+    logger.info`${pluginIdLogPrefix}: Invalid version name provided. Try something like: 1.0.0`;
+    throw err;
+  }
+
+  const versions = (await readVersionsFile(siteDir, pluginId)) ?? [];
+
+  // Check if version already exists.
+  if (versions.includes(version)) {
+    throw new Error(
+      `${pluginIdLogPrefix}: this version already exists! Use a version tag that does not already exist.`,
+    );
+  }
+
+  if (i18n.locales.length > 1) {
+    logger.info`Versioned docs will be created for the following locales: name=${i18n.locales}`;
+  }
+
+  await Promise.all(
+    i18n.locales.map(async (locale) => {
+      const localizationDir = path.resolve(
+        siteDir,
+        i18n.path,
+        getLocaleConfig(i18n, locale).path,
+      );
+      // Copy docs files.
+      const docsDir =
+        locale === i18n.defaultLocale
+          ? path.resolve(siteDir, docsPath)
+          : getDocsDirPathLocalized({
+              localizationDir,
+              pluginId,
+              versionName: CURRENT_VERSION_NAME,
+            });
+
+      if (
+        !(await pathExists(docsDir)) ||
+        (await fs.readdir(docsDir)).length === 0
+      ) {
+        if (locale === i18n.defaultLocale) {
+          throw new Error(
+            logger.interpolate`${pluginIdLogPrefix}: no docs found in path=${docsDir}.`,
+          );
+        } else {
+          logger.warn`${pluginIdLogPrefix}: no docs found in path=${docsDir}. Skipping.`;
+          return;
+        }
+      }
+
+      const newVersionDir =
+        locale === i18n.defaultLocale
+          ? getVersionDocsDirPath(siteDir, pluginId, version)
+          : getDocsDirPathLocalized({
+              localizationDir,
+              pluginId,
+              versionName: version,
+            });
+      // verbatimSymlinks: keep relative symlinks relative
+      await fs.cp(docsDir, newVersionDir, {
+        recursive: true,
+        verbatimSymlinks: true,
+      });
+
+      // Copy version JSON translation file for this locale
+      // i18n/<l>/docusaurus-plugin-content-docs/current.json => version-v1.json
+      // See https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#translation-files-location
+      if (locale !== i18n.defaultLocale) {
+        const dir = getPluginDirPathLocalized({
+          localizationDir,
+          pluginId,
+        });
+        const sourceFile = path.join(dir, 'current.json');
+        const dest = path.join(dir, `version-${version}.json`);
+        if (await pathExists(sourceFile)) {
+          await fs.cp(sourceFile, dest, {verbatimSymlinks: true});
+        } else {
+          logger.warn`${pluginIdLogPrefix}: i18n translation file does not exist in path=${sourceFile}. Skipping.`;
+        }
+      }
+    }),
+  );
+
+  await createVersionedSidebarFile({
+    siteDir,
+    pluginId,
+    version,
+    sidebarPath,
+  });
+
+  // Update versions.json file.
+  versions.unshift(version);
+  await outputFile(
+    getVersionsFilePath(siteDir, pluginId),
+    `${JSON.stringify(versions, null, 2)}\n`,
+  );
+
+  logger.success`name=${pluginIdLogPrefix}: version name=${version} created!`;
+}
+
+// TODO try to remove this workaround
+// Why use a default export instead of named exports here?
+// This is only to make Jest mocking happy
+// After upgrading Jest/SWC we got this weird mocking error in extendCli tests
+// "spyOn: Cannot redefine property cliDocsVersionCommand"
+// I tried various workarounds, and it's the only one that worked :/
+// See also:
+// - https://pyk.sh/fixing-typeerror-cannot-redefine-property-x-error-in-jest-tests#heading-solution-2-using-barrel-imports
+// - https://github.com/aelbore/esbuild-jest/issues/26
+// - https://stackoverflow.com/questions/67872622/jest-spyon-not-working-on-index-file-cannot-redefine-property/69951703#69951703
+export default {
+  cliDocsVersionCommand,
+};

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';
+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;
+}): ReactNode {
+  const contextValue = useContextValue(content);
+  return <Context value={contextValue}>{children}</Context>;
+}
+
+/**
+ * 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;
+}