Docusaurus: Dropdown with all versions

[swieczorek]

For software product documentation versioning is essential.

It would be great to have a dropdown with all versions available and with the active one highlighted.

As a good example you can check GitLab:

https://docs.gitlab.com/12.9/ee/README.html

You see directly that you are in version 12.9 and you can easily change to a previous one.

Versioning is already working with the alpha49 but the version in the top menu doesn't change if you visit an older version, it's a little bit confusing.

Thanks for your great work :-)

Best regards from Berlin,
Stefan Wieczorek

[lex111]

The Bootstrap website is a better example https://getbootstrap.com/
I think we need to do by analogy as there.

[fanny]

I think that was implemented here https://github.com/facebook/docusaurus/pull/2487, right?

[JoseRenan]

In this case, fixing the version on the topbar to display the version selected by the drop-down that @fanny shown resolves the problem? If so, could I work on it?

[fanny]

Could you confirm if this is the purpose of this issue? @lex111. IMO, you are right, @JoseRenan is confused, to select a version with the dropdown and see another on the topbar.

[yangshun]

This is quite hard because versioning should be a docs plugin-only concept. We also don't store in the state the currently viewing version so the navbar currently isn't able to fetch it. We might need to create new context components to allow components to fetch the currently viewed version.

[lunelson]

1. I agree it's confusing that you can change versions through the dropdown yet the right side of the navbar doesn't change to reflect this.
2. Also when you use the dropdown, it should preserve your location: if I'm viewing the page at https://v2.docusaurus.io/docs/2.0.0-alpha.54/markdown-features, then I use the dropdown to change to 2.0.0-alpha.56, the app should preserve the rest of my path if the same path exists—I should end up at https://v2.docusaurus.io/docs/markdown-features but currently I'm bounced back to https://v2.docusaurus.io/docs/.

[slorber]

Hi @lunelson.

Preserving the path is something complex, because:

• across versions, docs might be added/deleted/moved. Yet if the dropdown is always there, it must lead somewhere. /docs/next/doc1 could exist, yet /docs/0.1.0/doc1 might not exist, so we need a fallback in this case (which my be the "root" of a given version)
• the "root" of a given version is configurable, which adds some complexity :p It might be /, /docs, /docs/version, /docs/version/doc1...
• the code of the docs plugin is complicated already 🤪

I don't think we are going to support this soon, as it does not add much value and is complicated to implement.

---

About the other comments

@lunelson

I agree it's confusing that you can change versions through the dropdown yet the right side of the navbar doesn't change to reflect this.

@JoseRenan

In this case, fixing the version on the topbar to display the version selected by the drop-down that @fanny shown resolves the problem? If so, could I work on it?

As far as I understand, what's confusing is that, when I'm on version 1, it shows a static version 2 on the top navbar? (actually, the navbar constantly displays the "current version").

In this screenshot, I'm on a "next version" document, yet navbar displays v2.0.0-alpha.56

I agree this is quite confusing, and we should do something to fix that weird UX.

---

@yangshun said:

This is quite hard because versioning should be a docs plugin-only concept. We also don't store in the state the currently viewing version so the navbar currently isn't able to fetch it. We might need to create new context components to allow components to fetch the currently viewed version.

A possible implementation to solve this, is to use a "teleport" library. Basically, it permits to "reserve" a "slot" in the navbar, that will be filled from a component in a different tree.

So, the navbar would display the current docs version, but only if the user is on a document (eventually could fallback to current version for other pages like the homepage).

There are many of such libs:

• https://github.com/javivelasco/react-tunnels
• https://github.com/cloudflare/react-gateway
• https://github.com/gregberge/react-teleporter
• https://github.com/camwest/react-slot-fill

Don't know exactly what the api would look like, but that could be a way to let content plugins be able to "customize" parent/layout components without introducing too much coupling.

[lunelson]

Preserving the path is something complex [...] I don't think we are going to support this soon, as it does not add much value and is complicated to implement.

I'm not sure I can argue that it's particularly valuable, more that IMO it's a forced UX necessity since v2 implements a drop-down version switcher along with labels at the top of each page to indicate their version: the UX of that situation seems to imply the ability to "switch contexts" and IMO demands that when I switch, I stay on the same page (path) if possible. There must be a fallback, as you say, but I don't see how the actual logic of checking these paths is too complicated.

As far as I understand, what's confusing is that, when I'm on version 1, it shows a static version 2 on the top navbar? [...] I agree this is quite confusing

Yes this is what I mean. In v1 when you change versions the navbar _changes to reflect the version you are currently on_, which is clear

[slorber]

@lunelson actually someone else opened a similar issue here: https://github.com/facebook/docusaurus/issues/2923

but I don't see how the actual logic of checking these paths is too complicated.

Currently the navbar and the docs feature are decoupled, the code of both is in separate plugins that do not see each other's data, and the docs plugin is quite complicated. I have ideas to make this version switching without loosing context work, and make the docs plugin simpler, but it's not so simple (or if it is to you please submit a PR ^^)

Note: other sites don't necessarily preserve the current docs's context either (see https://getbootstrap.com/docs/4.0/layout/grid/). Can you give me a docs site that does this version switch correctly?

[lunelson]

@slorber ReadTheDocs does this, and seems to implement a fallback-to-nearest-index-page kind of logic for paths that don't exist https://bootstrap-datepicker.readthedocs.io/en/v1.8.0/markup.html

[slorber]

Thanks @lunelson

Do you know such page with the fallback you mentioned? Your link seems to actually exist, and wasn't able to find a good example so far

[lunelson]

@slorber sorry I might have been wrong, I thought I was on a sub-page in that example but it was just a page-anchor; in this example, it falls back to "page not found" https://docs.scrapy.org/en/0.22/topics/dynamic-content.html

[slorber]

Do you have the original working page?

I don't think this is a great experience to have a 404 after switching version ^^ if we do this, we'd rather make something better

[lunelson]

@slorber Sorry, yes, it's the same URL with latest in place of the version path

https://docs.scrapy.org/en/latest/topics/dynamic-content.html

[slorber]

So, a simple solution could be:

• update the pathname with the appropriate version X
• if the doc does not exist in such version, create a custom 404 page for the given version, suggestion the user to browse version X from its root / home doc / first doc

edit: actually it wouldn't work great for custom pages :/

[lunelson]

Yes, that's pretty much what I was imagining

[slorber]

Hey,

I've tried implementing this thing using react tunnel / teleport techniques. It does not seem possible to me to make it work with decent SSR support, as those lib would only "fill the slot" after mount, in a useLayoutEffect.

What I'm looking for now is to provide a way to add some lightweight global doc routes/version data to have a good non-hacky support.

I also think we should have a custom "versionDropdown" item type for the navbar items (probably need to rename links to items btw)

[lunelson]

a way to add some lightweight global doc routes/version data

That sounds good! global routes/version information will probably come in useful in other cases as well

[slorber]

Hey. You can track ongoing progress here: https://github.com/facebook/docusaurus/pull/2971

[slorber]

Hey, I'm closing in favor of this similar issue: https://github.com/facebook/docusaurus/issues/2923

Here's a preview, interested by your feedback

[slorber]

Hey all, this is feature is now released!
If you like it, don't forget to retweet 😄
https://twitter.com/docusaurus/status/1286715187983048704