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

[hrumhurum]

Motivation

Fix #10833

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

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

Test links

https://deploy-preview-10852--docusaurus-2.netlify.app/

Docs:

• https://deploy-preview-10852--docusaurus-2.netlify.app/docs/versioning/#docsVersionDropdown
• https://deploy-preview-10852--docusaurus-2.netlify.app/docs/api/themes/configuration/#navbar-docs-version-dropdown

Preview on another site: https://gp-temp-docusaurus-app1.netlify.app/eazfuscator.net

[facebook-github-bot]

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]

✅ [V2]

Name	Link
🔨 Latest commit	5475e3b
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/679ba76f21581f0008e76440
😎 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]

⚡️ Lighthouse report for the deploy preview of this PR

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

[facebook-github-bot]

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

[slorber]

The feature works thanks 👍

But I'd like a few things changed

[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

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ Auto-approved build (Review)	2 changed	Jan 30, 2025, 4:31 PM

[slorber]

LGTM thanks 👍

I simplified a bit and handled a few edge cases, and it's working as I expect now.

Notably, if the dropdown only has one version in it, and a custom label is provided, we should display that version also as the dropdown hover link, and ensure the custom provided label is also used in it.

[felipecrs]

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

It would be awesome if I could override docId and docsPluginId for each version too.

This would allow me to implement my own doc versions (for example cloning the same repository multiple times and switching each to a different release branch), while still leveraging the (much nicer) docsVersionDropdown. Right now, I use a plain dropdown.

[felipecrs]

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

It would be awesome if I could override docId and docsPluginId for each version too.

This would allow me to implement my own doc versions (for example cloning the same repository multiple times and switching each to a different release branch), while still leveraging the (much nicer) docsVersionDropdown. Right now, I use a plain dropdown.

Would you accept a PR for this, @slorber?

[slorber]

I'm not sure to understand but this seems weird to me. The versions dropdown is tightly coupled to a specific docs plugin instance and is not meant to be used across multiple docs plugins.

I would need a concrete example to understand the use case, can you create a repro and showing how it's less convenient to use a regular hardcoded dropdown?

[felipecrs]

Thanks a lot for replying, @slorber.

The short explanation of my use case is:

1. My markdown docs lives in the same repository as my product
2. My product has several branches (example: master, 1.0, 2.0, 3.0)
3. The idea of keeping documentation for all versions within master branch does work for me, the docs are kept up to date for each branch as these product versions are also kept receiving maintenance changes
4. I need Docusaurus to read the docs from each branch instead

Since Docusaurus has no such feature (reading docs versions from git branches), I'm doing a trick in my build process to have the same repository cloned multiple times in different directories and each of them pointing to a version branch.

Then, I create one docInstance for each of these directories.

It works great, but when compared to the regular "multiple versions" experience:

1. The dropdown does not reflect the current version that is selected when collapsed
2. There's no banner indicating you are viewing docs for an older version
3. There're no tags within the pages indicating which version the current document applies to

I can build a minimal sample repository if you want to play with this concept. Would you still like it?

[slorber]

3. The idea of keeping documentation for all versions within master branch does work for me, the docs are kept up to date for each branch as these product versions are also kept receiving maintenance changes
4. I need Docusaurus to read the docs from each branch instead

This seems contradictory to me: you either have the versioned docs on master, or on dedicated feature branches, not both at the same time? 🤔

---

Since Docusaurus has no such feature (reading docs versions from git branches), I'm doing a trick in my build process to have the same repository cloned multiple times in different directories and each of them pointing to a version branch.

Docusaurus doesn't care about Git and branches. It sees what you have on the filesystem and builds that.

Then, I create one docInstance for each of these directories.

The docs version dropdown is meant to be used within a single docs instance.

If you want to use it, you must put your versioned docs in versioned_docs, and not use separate instances.

If you want to support your specific use case, you would have to create your own navbar component, or compute a dynamic regular dropdown with code.

It works great, but when compared to the regular "multiple versions" experience:

1. The dropdown does not reflect the current version that is selected when collapsed
2. There's no banner indicating you are viewing docs for an older version
3. There're no tags within the pages indicating which version the current document applies to

I can build a minimal sample repository if you want to play with this concept. Would you still like it?

I don't think it would be helpful because I think you misunderstood what the new "versions" attribute does.

It is not a way to provide your own versions. Rather, it is a way to "limit" and "override" values of versions we already know about.

The versions attribute allows you to display a subset of the available docs versions in a given order.

If you pass any version name that does not exist in the versioned_docs folder, it will immediately error. You cannot use this attribute to "invent" a random version name.

I believe the UX you want to get is not the purpose of this built-in dropdown component. If you want to use it, you really MUST put your versions in versioned_docs instead of using multiple docs instances.

---

If you want a navbar component to solve your use case, it would be implemented in a totally different way. For example, we could build a new built-in navbar item component that lists all the docs (or blog?) plugin instances available as dropdown items.

But to implement that, it's better to create a dedicated proposal issue and design the feature independently of the current dropdown.

We'd also need to see if there is enough traction for this feature to be implemented in Docusaurus itself. You can already implement this feature in userland today (see #7227), and doing so is helpful to poll our community and see if others are also interested in this feature. If it's only for you, it's better not to have it built-in.

I guess it could make sense if you offer SDKs in many languages to have a dropdown with SDK > iOS / Android / React / RN. This is not exactly the case you thought about because yours is a bit hacky, but this more common case is likely to solve your edge case at the same time.

---

However:

2. There's no banner indicating _you are viewing docs for an older version

The banner is totally unrelated to the navbar item. We don't support such banner across docs instance, and you really have to use versioned_docs for that.

3. There're no tags within the pages indicating which version the current document applies to

Same, there's no tags because you are using multiple instances instead of versioning.

At best we could design a "docs plugin instance" tag which should make sense globally. For example in he more common SDK case, we could display an iOS or Android tag to indicate which SDK you are currently browsing.

Now if you want to name your SDK "1.0" and "2.0", that's a workaround and becomes your responsibility but we don't plan to support "versioning across multiple docs instances"

[felipecrs]

This seems contradictory to me: you either have the versioned docs on master, or on dedicated feature branches, not both at the same time? 🤔

I have docs for version master in the master branch. And I have docs for version 1.0 in the 1.0 branch. I hope that clarifies it. 😅

---

@slorber I read everything you wrote (thank you!) and I started evaluating whether I could simply automatically build the versioned_docs directory and versions.json through my build script.

The answer is: for some simpler cases, it's probably doable. For me, it is not, because my docs directory make references to files outside of the docs directory, but still within that same branch (code snippets using raw loader for example).

---

That said, I think the only thing I really need is to be able to override the versioned docs path and their edit URLs through the versions.json. Something like:

[
  "2.0": {
    "docsPath": "../my-repo-2.0/docs",
    "editUrl": "https://github.com/my-company/my-repo/tree/2.0/docs/"
  },
  "1.0": {
    "docsPath": "../my-repo-1.0/docs",
    "editUrl": "https://github.com/my-company/my-repo/tree/1.0/docs/"
  }
]

And then I could leverage native support for versioned docs.

What do you think?

[slorber]

The answer is: for some simpler cases, it's probably doable. For me, it is not, because my docs directory makes references to files outside of the docs directory, but still within that same branch (code snippets using raw loader for example).

If that's the case, the question is why those references are breaking? Because they use relative paths? Then you can use @site/src/xyz.pdf instead to make those references more "portable" and not break depending on where the MDX files are.

At the moment we don't provide a way to provide custom versioned docs paths. This would be technically possible but I believe it would be better to make your path references portable instead.

[felipecrs]

I believe only relative path references make sense in my case. For example, see this MDX:

# File definition

import CodeBlock from "@theme/CodeBlock";
import Definition from "!!raw-loader!../yamls/file.yaml";

<CodeBlock
  language="yaml"
  showLineNumbers
>
  {Definition}
</CodeBlock>

If I replaced with some @site reference, I would either no longer be referring to the file within the same version branch as the document itself, or I'd need to hardcode the path to the right version.

[slorber]

If I replaced with some @site reference, I would either no longer be referring to the file within the same version branch as the document itself, or I'd need to hardcode the path to the right version.

This seems to contradict what you say here.

The answer is: for some simpler cases, it's probably doable. For me, it is not, because my docs directory make references to files outside of the docs directory, but still within that same branch (code snippets using raw loader for example).

You only have 2 possible cases:

• case 1: your yaml file is inside the versioned branch docs dir: in which case you can use @site/<staticPath>
• case 2: your yaml file is outside the versioned branch docs dir: in which case you can use relative paths, and they shouldn't break because they are relative and docs/yaml are versioned together

---

Note: in any case you can write a remark plugin to "remap" the markdown and JSX links to something else that wouldn't break.

[felipecrs]

It is case 2. yamls are outside my docs dir. If it was case 1 I suppose relative paths would work too since everything inside docs would be resolvable anyway.

[slorber]

It's really hard to understand why @site wouldn't work in such case. Giving a concrete file system tree example would help.

[felipecrs]

Alright. I'll work on that.

[felipecrs]

@slorber again, thanks a lot for iterating through my "request".

I built the sample repository and raised this as a different issue. Let's please continue there.

Note: to keep the feature request as straight as possible, I took one step back and continued from #10852 (comment) and rather than later comments. I believe it will make sense once you try it yourself.