@docusaurus/theme-classic 3.7.0-canary-6206 → 3.7.0-canary-6209

package/lib/options.js

@@ -182,6 +182,11 @@ const DocsVersionDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
     dropdownActiveClassDisabled: utils_validation_1.Joi.boolean(),
     dropdownItemsBefore: utils_validation_1.Joi.array().items(DropdownSubitemSchema).default([]),
     dropdownItemsAfter: utils_validation_1.Joi.array().items(DropdownSubitemSchema).default([]),
+    versions: utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().min(1)).min(1), utils_validation_1.Joi.object()
+        .pattern(utils_validation_1.Joi.string().min(1), utils_validation_1.Joi.object({
+        label: utils_validation_1.Joi.string().min(1),
+    }))
+        .min(1)),
 });
 const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
     type: utils_validation_1.Joi.string().equal('localeDropdown').required(),

package/lib/theme/NavbarItem/DocsVersionDropdownNavbarItem.d.ts

@@ -6,4 +6,4 @@
  */
 import { type ReactNode } from 'react';
 import type { Props } from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
-export default function DocsVersionDropdownNavbarItem({ mobile, docsPluginId, dropdownActiveClassDisabled, dropdownItemsBefore, dropdownItemsAfter, ...props }: Props): ReactNode;
+export default function DocsVersionDropdownNavbarItem({ mobile, docsPluginId, dropdownActiveClassDisabled, dropdownItemsBefore, dropdownItemsAfter, versions: configs, ...props }: Props): ReactNode;

package/lib/theme/NavbarItem/DocsVersionDropdownNavbarItem.js

@@ -15,6 +15,35 @@ import {translate} from '@docusaurus/Translate';
 import {useLocation} from '@docusaurus/router';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
+function getVersionItems(versions, configs) {
+  if (configs) {
+    // Collect all the versions we have
+    const versionMap = new Map(
+      versions.map((version) => [version.name, version]),
+    );
+    const toVersionItem = (name, config) => {
+      const version = versionMap.get(name);
+      if (!version) {
+        throw new Error(`No docs version exist for name '${name}', please verify your 'docsVersionDropdown' navbar item versions config.
+Available version names:\n- ${versions.map((v) => `${v.name}`).join('\n- ')}`);
+      }
+      return {version, label: config?.label ?? version.label};
+    };
+    if (Array.isArray(configs)) {
+      return configs.map((name) => toVersionItem(name, undefined));
+    } else {
+      return Object.entries(configs).map(([name, config]) =>
+        toVersionItem(name, config),
+      );
+    }
+  } else {
+    return versions.map((version) => ({version, label: version.label}));
+  }
+}
+function useVersionItems({docsPluginId, configs}) {
+  const versions = useVersions(docsPluginId);
+  return getVersionItems(versions, configs);
+}
 function getVersionMainDoc(version) {
   return version.docs.find((doc) => doc.id === version.mainDocId);
 }
@@ -26,22 +55,36 @@ function getVersionTargetDoc(version, activeDocContext) {
     getVersionMainDoc(version)
   );
 }
+// The version item to use for the "dropdown button"
+function useDisplayedVersionItem({docsPluginId, versionItems}) {
+  // The order of the candidates matters!
+  const candidates = useDocsVersionCandidates(docsPluginId);
+  const candidateItems = candidates
+    .map((candidate) => versionItems.find((vi) => vi.version === candidate))
+    .filter((vi) => vi !== undefined);
+  return candidateItems[0] ?? versionItems[0];
+}
 export default function DocsVersionDropdownNavbarItem({
   mobile,
   docsPluginId,
   dropdownActiveClassDisabled,
   dropdownItemsBefore,
   dropdownItemsAfter,
+  versions: configs,
   ...props
 }) {
   const {search, hash} = useLocation();
   const activeDocContext = useActiveDocContext(docsPluginId);
-  const versions = useVersions(docsPluginId);
   const {savePreferredVersionName} = useDocsPreferredVersion(docsPluginId);
-  function versionToLink(version) {
+  const versionItems = useVersionItems({docsPluginId, configs});
+  const displayedVersionItem = useDisplayedVersionItem({
+    docsPluginId,
+    versionItems,
+  });
+  function versionItemToLink({version, label}) {
     const targetDoc = getVersionTargetDoc(version, activeDocContext);
     return {
-      label: version.label,
+      label,
       // preserve ?search#hash suffix on version switches
       to: `${targetDoc.path}${search}${hash}`,
       isActive: () => version === activeDocContext.activeVersion,
@@ -50,10 +93,9 @@ export default function DocsVersionDropdownNavbarItem({
   }
   const items = [
     ...dropdownItemsBefore,
-    ...versions.map(versionToLink),
+    ...versionItems.map(versionItemToLink),
     ...dropdownItemsAfter,
   ];
-  const dropdownVersion = useDocsVersionCandidates(docsPluginId)[0];
   // Mobile dropdown is handled a bit differently
   const dropdownLabel =
     mobile && items.length > 1
@@ -63,11 +105,12 @@ export default function DocsVersionDropdownNavbarItem({
           description:
             'The label for the navbar versions dropdown on mobile view',
         })
-      : dropdownVersion.label;
+      : displayedVersionItem.label;
   const dropdownTo =
     mobile && items.length > 1
       ? undefined
-      : getVersionTargetDoc(dropdownVersion, activeDocContext).path;
+      : getVersionTargetDoc(displayedVersionItem.version, activeDocContext)
+          .path;
   // We don't want to render a version dropdown with 0 or 1 item. If we build
   // the site with a single docs version (onlyIncludeVersions: ['1.0.0']),
   // We'd rather render a button instead of a dropdown

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "3.7.0-canary-6206",
+  "version": "3.7.0-canary-6209",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,19 +20,19 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.7.0-canary-6206",
-    "@docusaurus/logger": "3.7.0-canary-6206",
-    "@docusaurus/mdx-loader": "3.7.0-canary-6206",
-    "@docusaurus/module-type-aliases": "3.7.0-canary-6206",
-    "@docusaurus/plugin-content-blog": "3.7.0-canary-6206",
-    "@docusaurus/plugin-content-docs": "3.7.0-canary-6206",
-    "@docusaurus/plugin-content-pages": "3.7.0-canary-6206",
-    "@docusaurus/theme-common": "3.7.0-canary-6206",
-    "@docusaurus/theme-translations": "3.7.0-canary-6206",
-    "@docusaurus/types": "3.7.0-canary-6206",
-    "@docusaurus/utils": "3.7.0-canary-6206",
-    "@docusaurus/utils-common": "3.7.0-canary-6206",
-    "@docusaurus/utils-validation": "3.7.0-canary-6206",
+    "@docusaurus/core": "3.7.0-canary-6209",
+    "@docusaurus/logger": "3.7.0-canary-6209",
+    "@docusaurus/mdx-loader": "3.7.0-canary-6209",
+    "@docusaurus/module-type-aliases": "3.7.0-canary-6209",
+    "@docusaurus/plugin-content-blog": "3.7.0-canary-6209",
+    "@docusaurus/plugin-content-docs": "3.7.0-canary-6209",
+    "@docusaurus/plugin-content-pages": "3.7.0-canary-6209",
+    "@docusaurus/theme-common": "3.7.0-canary-6209",
+    "@docusaurus/theme-translations": "3.7.0-canary-6209",
+    "@docusaurus/types": "3.7.0-canary-6209",
+    "@docusaurus/utils": "3.7.0-canary-6209",
+    "@docusaurus/utils-common": "3.7.0-canary-6209",
+    "@docusaurus/utils-validation": "3.7.0-canary-6209",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "copy-text-to-clipboard": "^3.2.0",
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "cac332ad32e91b5f3a11bd34a5a17e55d12db267"
+  "gitHead": "402fd1ff0512991b1f7793c11d0ec2013b077b9b"
 }

package/src/options.ts

@@ -7,6 +7,10 @@
 
 import {themes} from 'prism-react-renderer';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
+import type {
+  PropVersionItem,
+  PropVersionItems,
+} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import type {Options, PluginOptions} from '@docusaurus/theme-classic';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import type {
@@ -210,6 +214,17 @@ const DocsVersionDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   dropdownActiveClassDisabled: Joi.boolean(),
   dropdownItemsBefore: Joi.array().items(DropdownSubitemSchema).default([]),
   dropdownItemsAfter: Joi.array().items(DropdownSubitemSchema).default([]),
+  versions: Joi.alternatives().try(
+    Joi.array().items(Joi.string().min(1)).min(1),
+    Joi.object<PropVersionItems>()
+      .pattern(
+        Joi.string().min(1),
+        Joi.object<PropVersionItem>({
+          label: Joi.string().min(1),
+        }),
+      )
+      .min(1),
+  ),
 });
 
 const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({

package/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

@@ -16,7 +16,11 @@ import {translate} from '@docusaurus/Translate';
 import {useLocation} from '@docusaurus/router';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
-import type {Props} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
+import type {
+  Props,
+  PropVersions,
+  PropVersionItem,
+} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 import type {
   GlobalVersion,
@@ -24,6 +28,56 @@ import type {
   ActiveDocContext,
 } from '@docusaurus/plugin-content-docs/client';
 
+type VersionItem = {
+  version: GlobalVersion;
+  label: string;
+};
+
+function getVersionItems(
+  versions: GlobalVersion[],
+  configs?: PropVersions,
+): VersionItem[] {
+  if (configs) {
+    // Collect all the versions we have
+    const versionMap = new Map<string, GlobalVersion>(
+      versions.map((version) => [version.name, version]),
+    );
+
+    const toVersionItem = (
+      name: string,
+      config?: PropVersionItem,
+    ): VersionItem => {
+      const version = versionMap.get(name);
+      if (!version) {
+        throw new Error(`No docs version exist for name '${name}', please verify your 'docsVersionDropdown' navbar item versions config.
+Available version names:\n- ${versions.map((v) => `${v.name}`).join('\n- ')}`);
+      }
+      return {version, label: config?.label ?? version.label};
+    };
+
+    if (Array.isArray(configs)) {
+      return configs.map((name) => toVersionItem(name, undefined));
+    } else {
+      return Object.entries(configs).map(([name, config]) =>
+        toVersionItem(name, config),
+      );
+    }
+  } else {
+    return versions.map((version) => ({version, label: version.label}));
+  }
+}
+
+function useVersionItems({
+  docsPluginId,
+  configs,
+}: {
+  docsPluginId: Props['docsPluginId'];
+  configs: Props['versions'];
+}): VersionItem[] {
+  const versions = useVersions(docsPluginId);
+  return getVersionItems(versions, configs);
+}
+
 function getVersionMainDoc(version: GlobalVersion): GlobalDoc {
   return version.docs.find((doc) => doc.id === version.mainDocId)!;
 }
@@ -40,23 +94,47 @@ function getVersionTargetDoc(
   );
 }
 
+// The version item to use for the "dropdown button"
+function useDisplayedVersionItem({
+  docsPluginId,
+  versionItems,
+}: {
+  docsPluginId: Props['docsPluginId'];
+  versionItems: VersionItem[];
+}): VersionItem {
+  // The order of the candidates matters!
+  const candidates = useDocsVersionCandidates(docsPluginId);
+  const candidateItems = candidates
+    .map((candidate) => versionItems.find((vi) => vi.version === candidate))
+    .filter((vi) => vi !== undefined);
+  return candidateItems[0] ?? versionItems[0]!;
+}
+
 export default function DocsVersionDropdownNavbarItem({
   mobile,
   docsPluginId,
   dropdownActiveClassDisabled,
   dropdownItemsBefore,
   dropdownItemsAfter,
+  versions: configs,
   ...props
 }: Props): ReactNode {
   const {search, hash} = useLocation();
   const activeDocContext = useActiveDocContext(docsPluginId);
-  const versions = useVersions(docsPluginId);
   const {savePreferredVersionName} = useDocsPreferredVersion(docsPluginId);
+  const versionItems = useVersionItems({docsPluginId, configs});
+  const displayedVersionItem = useDisplayedVersionItem({
+    docsPluginId,
+    versionItems,
+  });
 
-  function versionToLink(version: GlobalVersion): LinkLikeNavbarItemProps {
+  function versionItemToLink({
+    version,
+    label,
+  }: VersionItem): LinkLikeNavbarItemProps {
     const targetDoc = getVersionTargetDoc(version, activeDocContext);
     return {
-      label: version.label,
+      label,
       // preserve ?search#hash suffix on version switches
       to: `${targetDoc.path}${search}${hash}`,
       isActive: () => version === activeDocContext.activeVersion,
@@ -66,12 +144,10 @@ export default function DocsVersionDropdownNavbarItem({
 
   const items: LinkLikeNavbarItemProps[] = [
     ...dropdownItemsBefore,
-    ...versions.map(versionToLink),
+    ...versionItems.map(versionItemToLink),
     ...dropdownItemsAfter,
   ];
 
-  const dropdownVersion = useDocsVersionCandidates(docsPluginId)[0];
-
   // Mobile dropdown is handled a bit differently
   const dropdownLabel =
     mobile && items.length > 1
@@ -81,11 +157,13 @@ export default function DocsVersionDropdownNavbarItem({
           description:
             'The label for the navbar versions dropdown on mobile view',
         })
-      : dropdownVersion.label;
+      : displayedVersionItem.label;
+
   const dropdownTo =
     mobile && items.length > 1
       ? undefined
-      : getVersionTargetDoc(dropdownVersion, activeDocContext).path;
+      : getVersionTargetDoc(displayedVersionItem.version, activeDocContext)
+          .path;
 
   // We don't want to render a version dropdown with 0 or 1 item. If we build
   // the site with a single docs version (onlyIncludeVersions: ['1.0.0']),

package/src/theme-classic.d.ts

@@ -1257,11 +1257,22 @@ declare module '@theme/NavbarItem/DocsVersionDropdownNavbarItem' {
   import type {Props as DropdownNavbarItemProps} from '@theme/NavbarItem/DropdownNavbarItem';
   import type {LinkLikeNavbarItemProps} from '@theme/NavbarItem';
 
+  type PropVersionItem = {
+    readonly label?: string;
+  };
+
+  type PropVersionItems = {
+    readonly [version: string]: PropVersionItem;
+  };
+
+  type PropVersions = string[] | PropVersionItems;
+
   export interface Props extends DropdownNavbarItemProps {
     readonly docsPluginId?: string;
     readonly dropdownActiveClassDisabled?: boolean;
     readonly dropdownItemsBefore: LinkLikeNavbarItemProps[];
     readonly dropdownItemsAfter: LinkLikeNavbarItemProps[];
+    readonly versions?: PropVersions;
   }
 
   export default function DocsVersionDropdownNavbarItem(