Allow setting label for Versions Dropdown

[freef]

🐛 Bug Report

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io
• I have read the console error message carefully (if applicable)

Description

(A clear and concise description of what the bug is.)

Have you read the Contributing Guidelines on issues?

Yup

Steps to reproduce

Use https://new.docusaurus.io to create a CodeSandbox reproducible demo of the bug.

Versioning crashes CodeSandbox right now. Please use the example repo.

(Write your steps here:)

1. Create a project with multi-instance docs. Each set of documentation must be versioned. Documentation is available here.
2. Add a docsVersionDropdown navbar item for each set of docs as shown here
3. Resize window to collapse navbar to sidebar

Expected behavior

I expected the current version label to be moved to the sidebar.
(Write what you thought would happen.)

Actual behavior

The word 'Version' replaces the label for the current (or any) version. In projects with multiple docs this creates a really confusing user experience for anyone using the site on mobile.

It turns out this value is hard coded in the classic theme.

It would be great if I could override that label.

Your environment

• Public source code: N/A
• Public site URL: N/A
• Docusaurus version used: 2.0.0-beta 4
• Environment name and version (e.g. Chrome 78.0.3904.108, Node.js 10.17.0): Chrome Version 92.0.4515.131, Node.js v15.5.1
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): MacOSX BigSur 11.4

Reproducible demo

https://github.com/freef/docusaurus-error-example

[slorber]

Agree this is not good for versioned multi-instances!

What behavior would you like this to have?
How Docusaurus should decide which label to display?

If really needed, what kind of elegant API should we add to enable customizing this label?

[freef]

Hmmm... I think that the simplest solution would be to add a field called something like mobileLabel to the docsVersionDropdown with a default value of Version. Then change the line in the screenshot to

const dropdownLabel = mobile && items ? dropdownVersion.mobileLabel : dropdownVersion.label;

[Josh-Cena]

It doesn't make much sense to me to display two version dropdowns simultaneously anyways. In the end it's better if we can display dropdowns dynamically based on the active doc instance, but again—SSR is difficult

[freef]

Agreed. My ideal solution would be a version selector in the sidebar (instead of the navbar). Though that gets into feature request territory.

I imagine I'd still be annoyed with not being able to rename the version label on the mobile layout even in a single-doc project with a more conventional use of the version dropdown.

[slorber]

It doesn't make much sense to me to display two version dropdowns simultaneously anyways. In the end it's better if we can display dropdowns dynamically based on the active doc instance, but again—SSR is difficult

@Josh-Cena if you maintain ios/android sdks, it can make sense on the homepage (where you are not browsing any of those sdks yet). For sure it doesn't scale to a lot of docs plugin instances, but 2 should be fine and make sense to me.

My ideal solution would be a version selector in the sidebar (instead of the navbar). Though that gets into feature request territory.

@freef that's an interesting feature we could add. However we should take into consideration that a docs plugin instance may have multiple sidebars. Should all sidebars display that dropdown if the option is enabled? It doesn't make sense to me to configure this on a per-sidebar basis.

I imagine I'd still be annoyed with not being able to rename the version label on the mobile layout even in a single-doc project with more conventional use of the version dropdown.

Agree, we should add an option. Is mobileLabel the best name? I don't have better 🤪

[freef]

@slorber when it comes to adding this to a sidebar, I think it makes the most sense to create a new item type. That way it could be something added to a sidebar like any other item and the users can figure out which sidebar it belongs in. Like:

mySidebar: [
  {
      type: 'link',
      label: 'Home', 
      href: '/', 
    },
    {
      type: 'autogenerated',
      dirName: '.', 
  },
  {
    type: 'versionDropdown',
    docsPluginId: 'docs',
  },
]

I also don't have a better name than mobileLabel but I feel like there should be one. ¯\(ツ)/¯

[slorber]

Quite similar issue to consider @freef #7409

Note some sites are already using sidebar version dropdowns today:

https://apisix.apache.org/docs/apisix/getting-started
https://docs.dyte.io/react/quickstart

This currently requires swizzling the sidebar and a bit of React knowledge to make it work: https://github.com/apache/apisix-website/blob/master/website/src/theme/DocSidebar/index.tsx#L64

Would you still need to use a mobileLabel prop if this version dropdown were implemented as a first-class sidebar item type?

[andrewnicols]

Is there any progress on this or the possibility of having a non-swizzed doc sidebar version selector?

We've just started to version some of our docs and the feedback we have so far is that the UX is not ideal:

• The version dropdown shows the current version, but if you click on it (without waiting for it to open the dropdown) it takes you to the landing page for that doc
• Having it display the current version is not always intuitive
• it is not relevant for non-versioned docs.

I wonder whether the proposal that @slorber mentions to have it in the sidebar would resolve these issues and make it clearer, but I'm hesitant to swizzle this when it feels like it should be a core feature.

[slorber]

@andrewnicols if would help if you could share what's the target experience you aim for instead of what's not working at the moment. Do you know existing sites implementing exactly the UX you want?

The version dropdown shows the current version, but if you click on it (without waiting for it to open the dropdown) it takes you to the landing page for that doc

That doesn't seem like a bad default behavior and is consistent with all the other dropdowns we have.

Having it display the current version is not always intuitive

In which case? Who reported what problem exactly?

it is not relevant for non-versioned docs.

If your docs is unversioned, why would you use this version dropdown anyway 🤷‍♂️ you shouldn't use it.

I wonder whether the proposal that @slorber mentions to have it in the sidebar would resolve these issues and make it clearer, but I'm hesitant to swizzle this when it feels like it should be a core feature.

The core feature of Docusaurus is to be flexible and to allow you to bend it to your custom needs

If the version dropdown item doesn't work for you, it's possible to add your own custom navbar items: #7227

We could make it a select instead (ie the navbar element is a button instead of a link) but that would be a different navbar item type with a different ux and configuration, and things to take care of like accessibility.

Some users already do this: https://docs.dyte.io/react-native (open-source site)