facebook · hrumhurum · Jan 18, 2025 · Jan 18, 2025 · Jan 18, 2025 · Jan 18, 2025
@@ -827,6 +827,74 @@ describe('themeConfig', () => {
       );
     });
   });
+
+  describe('docsVersionDropdown', () => {
+    describe('versions', () => {
+      it('accepts array of strings', () => {
+        const config = {
+          navbar: {
+            items: [
+              {
+                type: 'docsVersionDropdown',
+                versions: ['current', '1.0'],
+              },
+            ],
+          },
+        };
+        testValidateThemeConfig(config);
+      });
+
+      it('rejects array of non-strings', () => {
+        const config = {
+          navbar: {
+            items: [
+              {
+                type: 'docsVersionDropdown',
+                versions: [1, 2],
+              },
+            ],
+          },
+        };
+        expect(() =>
+          testValidateThemeConfig(config),
+        ).toThrowErrorMatchingInlineSnapshot(
+          `""navbar.items[0].versions[0]" must be a string"`,
+        );
+      });
+
+      it('accepts dictionary of version objects', () => {
+        const config = {
+          navbar: {
+            items: [
+              {
+                type: 'docsVersionDropdown',
+                versions: {current: {}, '1.0': {label: '1.x'}},
+              },
+            ],
+          },
+        };
+        testValidateThemeConfig(config);
+      });
+
+      it('rejects dictionary of invalid objects', () => {
+        const config = {
+          navbar: {
+            items: [
+              {
+                type: 'docsVersionDropdown',
+                versions: {current: {}, '1.0': {invalid: '1.x'}},
+              },
+            ],
+          },
+        };
+        expect(() =>
+          testValidateThemeConfig(config),
+        ).toThrowErrorMatchingInlineSnapshot(
+          `""navbar.items[0].versions.1.0.invalid" is not allowed"`,
+        );
+      });
+    });
+  });
 });
 
 describe('validateOptions', () => {

@@ -8,6 +8,10 @@
 import {themes} from 'prism-react-renderer';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
 import type {Options, PluginOptions} from '@docusaurus/theme-classic';
+import type {
+  PropVersionItem,
+  PropVersionItems,
+} from '@theme/NavbarItem/DocsVersionDropdownNavbarItem';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import type {
   ThemeConfigValidationContext,
@@ -210,6 +214,15 @@ 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)),
+    Joi.object<PropVersionItems>().pattern(
+      Joi.string().min(1),
+      Joi.object<PropVersionItem>({
+        label: Joi.string().min(1),
+      }),
+    ),
+  ),
 });
 
 const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({

@@ -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(

@@ -16,14 +16,67 @@ 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,
   GlobalDoc,
   ActiveDocContext,
 } from '@docusaurus/plugin-content-docs/client';
 
+type VersionItem = {
+  version: GlobalVersion;
+  config?: PropVersionItem;
+};
+
+function getDropdownVersions(
+  versions: GlobalVersion[],
+  configs?: PropVersions,
+): VersionItem[] {
+  if (configs) {
+    // The versions are configured
+
+    // Collect all the versions we have
+    const versionMap = new Map<string, GlobalVersion>(
+      versions.map((version) => [version.name, version]),
+    );
+
+    function getVersionItem(
+      name: string,
+      config?: PropVersionItem,
+    ): VersionItem | undefined {
+      const version = versionMap.get(name);
+      if (!version) {
+        // A version configuration references a non-existing version, ignore it
+        return undefined;
+      }
+      return {version, config};
+    }
+
+    // Keep only versions specified in configuration, reorder them accordingly
+    let versionItems: (VersionItem | undefined)[];
+    if (Array.isArray(configs)) {
+      versionItems = configs.map((name) => getVersionItem(name, undefined));
+    } else {
+      versionItems = Object.entries(configs).map(([name, config]) =>
+        getVersionItem(name, config),
+      );
+    }
+
+    // Filter out ignored items
+    return versionItems.filter((x) => x !== undefined);
+  } else {
+    // The versions are not configured
+    return versions.map((version) => {
+      return {version, config: undefined};
+    });
+  }
+}
+
 function getVersionMainDoc(version: GlobalVersion): GlobalDoc {
   return version.docs.find((doc) => doc.id === version.mainDocId)!;
 }
@@ -46,17 +99,27 @@ export default function DocsVersionDropdownNavbarItem({
   dropdownActiveClassDisabled,
   dropdownItemsBefore,
   dropdownItemsAfter,
+  versions: versionConfigs,
   ...props
 }: Props): ReactNode {
+  // Build version list
+  const dropdownVersions = getDropdownVersions(
+    useVersions(docsPluginId),
+    versionConfigs,
+  );
+
+  // Build item list
   const {search, hash} = useLocation();
   const activeDocContext = useActiveDocContext(docsPluginId);
-  const versions = useVersions(docsPluginId);
   const {savePreferredVersionName} = useDocsPreferredVersion(docsPluginId);
 
-  function versionToLink(version: GlobalVersion): LinkLikeNavbarItemProps {
+  function versionToLink(
+    version: GlobalVersion,
+    config?: PropVersionItem,
+  ): LinkLikeNavbarItemProps {
     const targetDoc = getVersionTargetDoc(version, activeDocContext);
     return {
-      label: version.label,
+      label: config?.label ?? version.label,
       // preserve ?search#hash suffix on version switches
       to: `${targetDoc.path}${search}${hash}`,
       isActive: () => version === activeDocContext.activeVersion,
@@ -66,7 +129,7 @@ export default function DocsVersionDropdownNavbarItem({
 
   const items: LinkLikeNavbarItemProps[] = [
     ...dropdownItemsBefore,
-    ...versions.map(versionToLink),
+    ...dropdownVersions.map((item) => versionToLink(item.version, item.config)),
     ...dropdownItemsAfter,
   ];
 

@@ -597,11 +597,23 @@ Accepted fields:
 | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 | `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
+| `versions` | `DropdownVersions` | `undefined` | Specify a custom list of versions to include in the dropdown. See [the versioning guide](../../guides/docs/versioning.mdx#docsVersionDropdown) for details. |
 
 ```mdx-code-block
 </APITable>
 ```
 
+Types:
+
+```ts
+type DropdownVersion = {
+  /** The custom name to be shown in the dropdown for this version. */
+  label?: string;
+};
+
+type DropdownVersions = string[] | {[versionName: string]: DropdownVersion};
+```
+
 Example configuration:
 
 ```js title="docusaurus.config.js"

@@ -271,6 +271,75 @@ These links would all look for an appropriate version to link to, in the followi
 2. **Preferred version**: the version that the user last viewed. If there's no history, fall back to...
 3. **Latest version**: the default version that we navigate to, configured by the `lastVersion` option.
 
+## `docsVersionDropdown` {#docsVersionDropdown}
+
+By default, the [`docsVersionDropdown`](../../api/themes/theme-configuration.mdx#navbar-docs-version-dropdown) displays all the versions provided by the docs. However, sometimes it may be beneficial to restrict the number of displayed versions to simplify the user experience. To achieve that, it is possible to specify a custom list of versions that should be offered in the dropdown:
+
+```js title="docusaurus.config.js"
+export default {
+  themeConfig: {
+    navbar: {
+      items: [
+        {
+          type: 'docsVersionDropdown',
+          // highlight-start
+          versions: ['current', '2024.2', '2024.1', '2023.4'],
+          // highlight-end
+        },
+      ],
+    },
+  },
+};
+```
+
+Some versioning schemes may benefit from an even more detailed configuration of displayed versions. For example, if you are using semantic versioning, you may have versions such as:
+
+```
+2.1.1
+2.1.0
+2.0.1
+2.0.0
+1.0.1
+1.0.0
+```
+
+And maybe you want to have them in the dropdown as:
+
+```
+2.1
+2.0
+1.0
+```
+
+or maybe just:
+
+```
+1.x
+2.x
+```
+
+To achieve that, you can specify a custom configuration for every version that should be displayed in the dropdown:
+
+```js title="docusaurus.config.js"
+export default {
+  themeConfig: {
+    navbar: {
+      items: [
+        {
+          type: 'docsVersionDropdown',
+          // highlight-start
+          versions: {
+            '1.0.1': {label: '1.x'},
+            '2.1.1': {label: '2.x'},
+          },
+          // highlight-end
+        },
+      ],
+    },
+  },
+};
+```
+
 ## Recommended practices {#recommended-practices}
 
 ### Version your documentation only when needed {#version-your-documentation-only-when-needed}