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

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

Motivation

The docsVersionDropdown navbar item supports a new versions attribute to filter/whitelist displayed versions. Only the provided versions will be displayed.

Example:

{
  type: 'docsVersionDropdown',
  versions: ['1.0.1', '2.1.1']
},

Also gives the ability to override version attributes (for now, only display label) by providing an object.

{
  type: 'docsVersionDropdown',
  versions: {
  '1.0.1': {label: '1.x'},
  '2.1.1': {label: '2.x'},
},

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

…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 cla@meta.com. Thanks!

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

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`1f3ec76`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/678e5a7aaaf29f00085cb840
😎 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
/	🔴 39	🟢 98	🟢 96	🟢 100	Report
/docs/installation	🔴 49	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 72	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 62	🟢 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

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

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

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

I am not a fan of that too but it's a workaround for a serious usability omission. Without that logic, a user faces a specifically annoying inconvenience.

Suppose a user wants to restrict the displayed versions to:

versions: ['2024.3','2024.2','2024.1','2023.4']

But without that logic, that aforementioned statement will not work. The user will be forced to specify something hacky like:

versions: ['current','2024.2','2024.1','2023.4']

or even:

versions: ['next','current','2024.1','2023.4']

This is technically ok, but it breaks mental expectations of the user. It can be clearly seen in the guide: it is simple now, but if we try to communicate "you cannot specify the current version by its true name, you must use the special keyword name 'current' because we have particular internals XXX in our code". Well, it will look inconvenient and broken to the user.

The right way to overcome that is to add the original name property to the GlobalVersion type:

export type GlobalVersion = { name: string; + /** The true version name as defined in the config */ + canonicalName: string; label: string; isLast: boolean; path: string; /** The doc with `slug: /`, or first doc in first sidebar */ mainDocId: string; docs: GlobalDoc[]; /** Unversioned IDs. In development, this list is empty. */ draftIds: string[]; sidebars?: {[sidebarId: string]: GlobalSidebar}; };

and then use it as a secondary (or primary) version identifier.

I understand the usability concern.

However, introducing this "shortcut" only there also introduces inconsistencies. If we add such a shortcut, we add it globally, in a consistent way, in every single place affected.

I'd prefer if this PR omits the shortcut, and that we discuss it independently, in another dedicated proposal and PR.

Note that there are various places where we have to document next/current version names already. Unless we find a way to remove these "magic identifiers" from everywhere, we can't escape from educating users about it.

https://docusaurus.io/docs/next/versioning
https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs

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

…m: inline options schema

… the versioning guide

…m: cleaned up reference docs

…m: fixed link

slorber

Still think we shouldn't include the "version name/label shortcut" in this PR, and discuss it independently in another proposal.

Let me know if you can simplify your code, otherwise I'll do it

slorber · 2025-01-23T12:03:45Z

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

+  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),
+      }),
+    ),
+  ),


can you add some basic tests in packages/docusaurus-theme-classic/src/__tests__/options.test.ts ?

We are not covering everything properly but adding tests for Joi schema is good. Joi often has surprisingly weird behaviors.

slorber · 2025-01-23T12:11:00Z

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);


I understand the usability concern.

However, introducing this "shortcut" only there also introduces inconsistencies. If we add such a shortcut, we add it globally, in a consistent way, in every single place affected.

I'd prefer if this PR omits the shortcut, and that we discuss it independently, in another dedicated proposal and PR.

Note that there are various places where we have to document next/current version names already. Unless we find a way to remove these "magic identifiers" from everywhere, we can't escape from educating users about it.

https://docusaurus.io/docs/next/versioning
https://docusaurus.io/docs/next/api/plugins/@docusaurus/plugin-content-docs

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

slorber · 2025-01-23T12:17:44Z

website/docs/guides/docs/versioning.mdx

@@ -271,6 +271,78 @@ 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.

+## Configuring representation of versions {#configuring-representation}


I'm not sure to like this docs heading. What does "representation" means.

This PR is only affecting one specific navbar item, not the "global representation of a specific version" (we have options.versions for that). I'd prefer if it was a subheading such as:

## Navbar items previous text ### `docsVersionDropdown`

Eventually, we'll want one subheading per navbar item with more details and examples. But that can be done in another docs PR.

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

hrumhurum added 3 commits January 20, 2025 12:47

feat(theme): add versions attribute to docsVersionDropdown navbar ite…

88e306c

…m: inline options schema

docs(theme): added "configuring versioning representation" section to…

9088e6c

… the versioning guide

docs(theme): add versions attribute to docsVersionDropdown navbar ite…

f74b638

…m: cleaned up reference docs

hrumhurum requested a review from slorber January 20, 2025 14:12

docs(theme): add versions attribute to docsVersionDropdown navbar ite…

1f3ec76

…m: fixed link

slorber requested changes Jan 23, 2025

View reviewed changes

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 by slorber

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

hrumhurum Jan 20, 2025

slorber Jan 23, 2025

slorber left a comment

slorber Jan 23, 2025

slorber Jan 23, 2025

slorber Jan 23, 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 by slorber Loading

Motivation

Test Plan

Test links

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

hrumhurum Jan 20, 2025

Choose a reason for hiding this comment

slorber Jan 23, 2025

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

slorber Jan 23, 2025

Choose a reason for hiding this comment

slorber Jan 23, 2025

Choose a reason for hiding this comment

slorber Jan 23, 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 by slorber

Loading

netlify bot commented Jan 18, 2025 •

edited

Loading

github-actions bot commented Jan 18, 2025 •

edited

Loading