@docusaurus/plugin-content-docs 3.3.2 → 3.5.0

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,9 +4,8 @@
  * 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 { BrokenMarkdownLink, Tag } from '@docusaurus/utils';
-import type { VersionMetadata, LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
+import type { TagMetadata } from '@docusaurus/utils';
+import type { LoadedVersion, CategoryGeneratedIndexMetadata } from '@docusaurus/plugin-content-docs';
 import type { SidebarsUtils } from './sidebars/utils';
 export type DocFile = {
     contentPath: string;
@@ -14,10 +13,7 @@ export type DocFile = {
     source: string;
     content: string;
 };
-export type SourceToPermalink = {
-    [source: string]: string;
-};
-export type VersionTag = Tag & {
+export type VersionTag = TagMetadata & {
     /** All doc ids having this tag. */
     docIds: string[];
     unlisted: boolean;
@@ -29,10 +25,3 @@ export type FullVersion = LoadedVersion & {
     sidebarsUtils: SidebarsUtils;
     categoryGeneratedIndices: CategoryGeneratedIndexMetadata[];
 };
-export type DocBrokenMarkdownLink = BrokenMarkdownLink<VersionMetadata>;
-export type DocsMarkdownOption = {
-    versionsMetadata: VersionMetadata[];
-    siteDir: string;
-    sourceToPermalink: SourceToPermalink;
-    onBrokenMarkdownLink: (brokenMarkdownLink: DocBrokenMarkdownLink) => void;
-};

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';
@@ -38,3 +37,4 @@ export declare function readVersionsMetadata({ context, options, }: {
     options: PluginOptions;
 }): Promise<VersionMetadata[]>;
 export declare function toFullVersion(version: LoadedVersion): FullVersion;
+export declare function getVersionFromSourceFilePath(filePath: string, versionsMetadata: VersionMetadata[]): VersionMetadata;

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.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,4 +171,10 @@ 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) {
+        throw new Error(`Unexpected error: file at "${filePath}" does not belong to any docs version!`);
+    }
+    return versionFound;
+}

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.3.2",
+  "version": "3.5.0",
   "description": "Docs plugin for Docusaurus.",
   "main": "lib/index.js",
   "sideEffects": false,
@@ -35,14 +35,15 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@docusaurus/core": "3.3.2",
-    "@docusaurus/logger": "3.3.2",
-    "@docusaurus/mdx-loader": "3.3.2",
-    "@docusaurus/module-type-aliases": "3.3.2",
-    "@docusaurus/types": "3.3.2",
-    "@docusaurus/utils": "3.3.2",
-    "@docusaurus/utils-common": "3.3.2",
-    "@docusaurus/utils-validation": "3.3.2",
+    "@docusaurus/core": "3.5.0",
+    "@docusaurus/logger": "3.5.0",
+    "@docusaurus/mdx-loader": "3.5.0",
+    "@docusaurus/module-type-aliases": "3.5.0",
+    "@docusaurus/theme-common": "3.5.0",
+    "@docusaurus/types": "3.5.0",
+    "@docusaurus/utils": "3.5.0",
+    "@docusaurus/utils-common": "3.5.0",
+    "@docusaurus/utils-validation": "3.5.0",
     "@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": "bc638d674bfbde1e254ef306697f47e764b5e107"
+  "gitHead": "cb5829f3c34b26d798b869e38ee25073488140bd"
 }

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;
+}

package/src/client/docSidebarItemsExpandedState.tsx

@@ -0,0 +1,55 @@
+/**
+ * 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, {type ReactNode, useMemo, useState, useContext} from 'react';
+import {ReactContextError} from '@docusaurus/theme-common/internal';
+
+type ContextValue = {
+  /**
+   * The item that the user last opened, `null` when there's none open. On
+   * initial render, it will always be `null`, which doesn't necessarily mean
+   * there's no category open (can have 0, 1, or many being initially open).
+   */
+  expandedItem: number | null;
+  /**
+   * Set the currently expanded item, when the user opens one. Set the value to
+   * `null` when the user closes an open category.
+   */
+  setExpandedItem: (a: number | null) => void;
+};
+
+const EmptyContext: unique symbol = Symbol('EmptyContext');
+const Context = React.createContext<ContextValue | typeof EmptyContext>(
+  EmptyContext,
+);
+
+/**
+ * Should be used to wrap one sidebar category level. This provider syncs the
+ * expanded states of all sibling categories, and categories can choose to
+ * collapse itself if another one is expanded.
+ */
+export function DocSidebarItemsExpandedStateProvider({
+  children,
+}: {
+  children: ReactNode;
+}): JSX.Element {
+  const [expandedItem, setExpandedItem] = useState<number | null>(null);
+  const contextValue = useMemo(
+    () => ({expandedItem, setExpandedItem}),
+    [expandedItem],
+  );
+
+  return <Context.Provider value={contextValue}>{children}</Context.Provider>;
+}
+
+export function useDocSidebarItemsExpandedState(): ContextValue {
+  const value = useContext(Context);
+  if (value === EmptyContext) {
+    throw new ReactContextError('DocSidebarItemsExpandedStateProvider');
+  }
+  return value;
+}

package/src/client/docsClientUtils.ts

@@ -63,14 +63,23 @@ export function getActiveVersion(
   data: GlobalPluginData,
   pathname: string,
 ): GlobalVersion | undefined {
-  const lastVersion = getLatestVersion(data);
-  // Last version is a route like /docs/*,
-  // 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,
-  ];
-  return orderedVersionsMetadata.find(
+  // Sort paths so that a match-all version like /docs/* is matched last
+  // Otherwise /docs/* would match /docs/1.0.0/* routes
+  // This is simplified but similar to the core sortRoutes() logic
+  const sortedVersions = [...data.versions].sort((a, b) => {
+    if (a.path === b.path) {
+      return 0;
+    }
+    if (a.path.includes(b.path)) {
+      return -1;
+    }
+    if (b.path.includes(a.path)) {
+      return 1;
+    }
+    return 0;
+  });
+
+  return sortedVersions.find(
     (version) =>
       !!matchPath(pathname, {
         path: version.path,