feat(theme): add `versions` attribute to `docsVersionDropdown` navbar item #10852

hrumhurum · 2025-01-18T18:05:33Z

Pre-flight checklist

I have read the Contributing Guidelines on pull requests.
If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
If this is a new API or substantial change: the PR has an accompanying issue (covers Limiting number of versions visible in the version dropdown switch #10833) and the maintainers have approved on my working plan.

Motivation

This PR implements a part of the functionality required to complete the feature.

Test Plan

Go to the deploy preview website
Locate the docs version dropdown in the upper part of the website
Click on the dropdown
Notice how the version titles are customized
Notice how the list of versions are customized to display just a subset of versions
Visit Docusaurus documentation preview to take a look at the documentation for new functionality

Test links

Deploy preview: https://gp-temp-docusaurus-app1.netlify.app/eazfuscator.net

Related issues/PRs

Limiting number of versions visible in the version dropdown switch #10833

…ionDropdown" navbar item

…rsionDropdown" navbar item

…sVersionDropdown" navbar item

facebook-github-bot · 2025-01-18T18:05:38Z

Hi @hrumhurum!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at [email protected]. Thanks!

netlify · 2025-01-18T18:08:01Z

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`a5afe09`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/678d7ae0b5ae460008725647
😎 Deploy Preview	https://deploy-preview-10852--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2025-01-18T18:10:30Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🔴 47	🟢 98	🟢 96	🟢 100	Report
/docs/installation	🟠 51	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 73	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 61	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🔴 46	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 63	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 73	🟢 100	🟢 100	🟠 86	Report

facebook-github-bot · 2025-01-18T18:14:26Z

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Meta Open Source project. Thanks!

…ration of "docsVersionDropdown" navbar item

…ion of "docsVersionDropdown" navbar item

…"docsVersionDropdown" navbar item

…on docs of "docsVersionDropdown" navbar item

…gurations in "docsVersionDropdown" navbar item

…ions in "docsVersionDropdown" navbar item

…navbar item: code refactoring

slorber

The feature works thanks 👍

But I'd like a few things changed

slorber · 2025-01-20T08:29:23Z

packages/docusaurus-theme-classic/src/options.ts

@@ -204,12 +208,23 @@ const DropdownNavbarItemSchema = NavbarItemBaseSchema.append({
  items: Joi.array().items(DropdownSubitemSchema).required(),
 });

+const DocsVersionNameSchema = Joi.string().min(1);


I'd prefer to "inline" this schema because it's tightly coupled to the dropdown but its name makes me thing it is a more general purpose schema. If we don't inline it, we'd rather have a "scoped name" such as DocsVersionDropdownVersionNameSchema which is a bit awkward. Considering the schema is relatively simple it's not a big deal if inlining means duplicating twice.

slorber · 2025-01-20T09:21:39Z

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

+  configuration?: VersionConfiguration;
+};
+
+function configureVersions(


Hmmm that looks a bit complicated to me.

Here's some pseudo-code I'd write to normalize the 3 cases under a single one:

type VersionConfig = { label?: string } type VersionItem = { version: GlobalVersion, config?: VersionConfig } function getDropdownVersions({versions,item)}): VersionItem[] { const versionMap = new Map<string, GlobalVersion>( versions.map((version) => [version.name, version]), ); if ( item.versions ) { // Maybe fail-fast if the user provide version names that do not exist // But it's preferable to do this earlier in Node.js side, if possible if (Array.isArray(item.versions)) { return item.versions.map(name => ({ version: versionMap[name], config: undefined; })); } else { // pseudo code: in practice, we don't want to import Lodash in theme code return _.mapValues(item.versions,(config,name) => ({ version: versionMap[name], config, })); } } else { return versions.map(v => ({version, config: undefined}) } }

slorber · 2025-01-20T09:22:11Z

packages/docusaurus-theme-classic/src/theme/NavbarItem/DocsVersionDropdownNavbarItem.tsx

+      // that's why we use 'version.label' as a secondary version identifier
+      // that can be referenced in configuration
+      const label = version.label;
+      if (!versionMap.has(label)) versionMap.set(label, version);


Not super fan of this logic.
We don't do this kind of thing anywhere else in the codebase so I'd prefer not introduce this here

slorber · 2025-01-20T09:25:26Z

website/docs/api/themes/theme-configuration.mdx

@@ -597,6 +597,7 @@ 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` | <code>string[] \| object</code> | `undefined` | Specify a custom list of versions to include in the dropdown, or specify an object with detailed version configurations. |


We'd need to document a type/shape, not just object

If needed, as a "Types: " code block, similar to what we do in other places such as https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs#types

(since the example is not a heading, no need to create a ### Types heading here for consistency)

What I'd do:

Types: ```ts type DropdownVersions = string[] | {[name: string]: {label?: string}} ```

slorber · 2025-01-20T09:37:51Z

website/docs/api/themes/theme-configuration.mdx

+By default, the version dropdown displays all the versions provided by the docs.
+However, sometimes it may be beneficial to restrict the number of displayed versions to declutter the UI.
+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: ['2024.3', '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
+        },
+      ],
+    },
+  },
+};
+```
+
+The fields accepted by the custom version configuration:
+
+```mdx-code-block
+<APITable name="navbar-docs-version-dropdown-configuration">
+```
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` | Optional | The custom name to be shown in the dropdown for this version. |
+
+```mdx-code-block
+</APITable>
+```
+


We are in the "reference docs" section, which is concise and formal on purpose.

However, sometimes it may be beneficial to restrict the number of displayed versions to declutter the UI

What you write here is more in the tone of a "guide" rather than "reference docs". It has an opinion on how this feature should be used and explains it in depth.
This kind of thing belongs to another place, such as this one:

https://docusaurus.io/docs/next/versioning#navbar-items

Can you please keep this section as concise, formal, and normaliezed as possible?

The idea is to just have one table of attributes, one config example, and if needed a types code block, and nothing more.

Note: if you really want to write this "opinionated guide" about this new feature, we'd probably need to document all the other navbar items one by one here for consistency: https://docusaurus.io/docs/next/versioning#navbar-items

Since we don't have that already, maybe it's better to do that in a separate docs-only PR so that we don't block this PR being merged due to docs organization concerns

hrumhurum added 3 commits January 18, 2025 16:43

feat(theme-classic): implemented version configurations for "docsVers…

544045f

…ionDropdown" navbar item

docs(theme-classic): added docs for versions configuration of "docsVe…

36a35e5

…rsionDropdown" navbar item

feat(theme-classic): preserve order of version configurations in "doc…

5e8032b

…sVersionDropdown" navbar item

hrumhurum requested review from slorber and Josh-Cena as code owners January 18, 2025 18:05

hrumhurum mentioned this pull request Jan 18, 2025

Limiting number of versions visible in the version dropdown switch #10833

Open

2 tasks

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jan 18, 2025

hrumhurum added 8 commits January 18, 2025 19:27

docs(theme-classic): fixed docs formatting issue for versions configu…

0a02b47

…ration of "docsVersionDropdown" navbar item

docs(theme-classic): improved wording in docs for versions configurat…

c791a47

…ion of "docsVersionDropdown" navbar item

docs(theme-classic): more precise docs for versions configuration of …

8e21202

…"docsVersionDropdown" navbar item

docs(theme-classic): fixed anchor for versions configuration docs of …

fd8f2db

…"docsVersionDropdown" navbar item

docs(theme-classic): simplified example code for versions configurati…

10976ad

…on docs of "docsVersionDropdown" navbar item

feat(theme-classic): use formal version identifiers for version confi…

bcae6cb

…gurations in "docsVersionDropdown" navbar item

feat(theme-classic): implementation refactoring of version configurat…

9e166c3

…ions in "docsVersionDropdown" navbar item

feat(theme-classic): version configurations in "docsVersionDropdown" …

a5afe09

…navbar item: code refactoring

slorber requested changes Jan 20, 2025

View reviewed changes

slorber changed the title ~~Implementation and docs for versions configuration of "docsVersionDropdown" navbar item~~ feat(theme):Add versions attribute to docsVersionDropdown navbar item Jan 20, 2025

slorber changed the title ~~feat(theme):Add versions attribute to docsVersionDropdown navbar item~~ feat(theme): add versions attribute to docsVersionDropdown navbar item Jan 20, 2025

slorber added the pr: new feature This PR adds a new API or behavior. label Jan 20, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(theme): add `versions` attribute to `docsVersionDropdown` navbar item #10852

feat(theme): add `versions` attribute to `docsVersionDropdown` navbar item #10852

hrumhurum commented Jan 18, 2025 •

edited

Loading

facebook-github-bot commented Jan 18, 2025

netlify bot commented Jan 18, 2025 •

edited

Loading

github-actions bot commented Jan 18, 2025 •

edited

Loading

facebook-github-bot commented Jan 18, 2025

slorber left a comment

slorber Jan 20, 2025

slorber Jan 20, 2025

slorber Jan 20, 2025

slorber Jan 20, 2025

slorber Jan 20, 2025 •

edited

Loading

slorber Jan 20, 2025

feat(theme): add versions attribute to docsVersionDropdown navbar item #10852

Are you sure you want to change the base?

feat(theme): add versions attribute to docsVersionDropdown navbar item #10852

Conversation

hrumhurum commented Jan 18, 2025 • edited Loading

Pre-flight checklist

Motivation

Test Plan

Test links

Related issues/PRs

facebook-github-bot commented Jan 18, 2025

Action Required

Process

netlify bot commented Jan 18, 2025 • edited Loading

✅ [V2]

github-actions bot commented Jan 18, 2025 • edited Loading

⚡️ Lighthouse report for the deploy preview of this PR

facebook-github-bot commented Jan 18, 2025

slorber left a comment

Choose a reason for hiding this comment

slorber Jan 20, 2025

Choose a reason for hiding this comment

slorber Jan 20, 2025

Choose a reason for hiding this comment

slorber Jan 20, 2025

Choose a reason for hiding this comment

slorber Jan 20, 2025

Choose a reason for hiding this comment

slorber Jan 20, 2025 • edited Loading

Choose a reason for hiding this comment

slorber Jan 20, 2025

Choose a reason for hiding this comment

feat(theme): add `versions` attribute to `docsVersionDropdown` navbar item #10852

feat(theme): add `versions` attribute to `docsVersionDropdown` navbar item #10852

hrumhurum commented Jan 18, 2025 •

edited

Loading

netlify bot commented Jan 18, 2025 •

edited

Loading

github-actions bot commented Jan 18, 2025 •

edited

Loading

slorber Jan 20, 2025 •

edited

Loading