Open respective tab item with URL query string

[YOU54F]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Description

Can multi-language support code blocks, support anchors which allow the anchored code block to open?

https://docusaurus-five-rho.vercel.app/docs/markdown-features/code-blocks#multi-language-support-code-block

For example, I would like to be able to offer a user a link, either via the docusaurus side bar, or directly, that allows them to jump to a language specific block.

EG clicking Java https://docusaurus-five-rho.vercel.app/docs/markdown-features/code-blocks#java would navigate to that part of the page and make that tab visible.

• The anchor link from the side bar will only work if the anchor is visible
• Hotlinking via the full url plus anchor if in a code block, will not move to the code block even if the anchor is in a visible tab.

This might just be a limitation of my HTML scripting foo, as is possible, if so, please show me the way!

Has this been requested on Canny?

No response

Motivation

we support an open source project which has a significant feature set across multiple language implementations.

I would like to be able to connect this up with syncing tab choices as it would enable readers to ensure they only see information that is relevant to them, in their preferred programming language.

API design

No response

Have you tried building it?

Yes, See example from docusaurus master, only addition is https://github.com/YOU54F/docusaurus/commit/0e297b966a34e68c4d612a42b1ad3f634d923395 to insert anchors on each of the code block tabs.

Deployed here via vercel however the headers aren't showing

https://docusaurus-you54f.vercel.app/docs/markdown-features/code-blocks

You can clone my master branch g clone [email protected]:YOU54F/docusaurus.git

npm install && cd website && npm start

Headers added and visible locally

clicking from TOC will anchor to Javascript tab

If java tab is pre selected and therefore visible

clicking from TOC will anchor to Java tab

Hot linking to any of the code block anchors http://localhost:3000/docs/markdown-features/code-blocks#javascript even the visible javascript one will take the user to the top of the page.

Self-service

• [X] I'd be willing to contribute this feature to Docusaurus myself.

[Josh-Cena]

It's also here: https://docusaurus.canny.io/feature-requests/p/link-to-tab

I think implementing one would be relatively easy. In addition to reading local storage we would also read URL, probably search params instead of hash.

[Celtech]

Not to add noise, but I second this feature request, would be a nice addition!

[lorensr]

Hi @YOU54F, great FR, appreciate you submitting! Wanted to check whether you're still up for submitting a PR for this?

[Josh-Cena]

If anyone wants to try their hands on this, feel free to.

The UX is a bit hard to design. For example, a user opens a URL with a query, and toggles the tabs. should the query be persisted? Should it be erased? Local storage and query—which takes priority? Do we need to automatically scroll to that tab like anchors do? If so, how would synced tab groups work?

[YOU54F]

Hey @lorensr / @Josh-Cena I would love to, as it would be such a valuable addition to our docs, but I am across a bit too much at the moment.

Saying that I would be happy working with you all, and having a good think about the design.

Do you guys just work across here or do you have a slack space,

[Josh-Cena]

We have a Discord server. See https://docusaurus.io/community/support#discussion-forums — you can chat in #contributors if you want to discuss about working on this feature. I don't have any strong opinions, so anyone wanting to try can do whatever they want.

[lorensr]

Re: UX, here are my personal prefs:

• User opens /page?tab=javascript#heading
• JavaScript tab group is opened (regardless of LocalStorage)
• If there isn't an existing LocalStorage tab choice saved, save it as JavaScript. If there is, don't overwrite it.

Do we need to automatically scroll to that tab like anchors do?

I wouldn't change the default browser behavior of setting scrollTop to #heading location. Unless that doesn't work for headings inside the tab? In which case I'd add code to enable that.

[Josh-Cena]

Tabs render eagerly by default, so I do think the DOM is available before hydration. I'm mainly thinking about /page?tab=javascript—do we scroll to the first tab group on the page with a JavaScript option?

Also note that there may be multiple tab groups on one page with the same choice name, but are not necessarily synced. So I think we need ?tabs='{"lang":"javascript","os": "mac","computer":"mac"}'. That's why the query is not easy to define...

[lorensr]

I'm mainly thinking about /page?tab=javascript—do we scroll to the first tab group on the page with a JavaScript option?

I'd say no, for flexibility's sake. If we autoscroll, then link creator can't link to the top of the page. Versus if we don't, then link creator can link to the relevant heading if they want to.

Also note that there may be multiple tab groups on one page with the same choice name, but are not necessarily synced.

Perhaps:

?tab=javascript

Changes all tabs that have a /javascript/i value to that value.

?tab=javascript&id=foo

Changes all <Tabs> with id=foo or groupId=foo.

[lorensr]

On a separate note, I think it would be nice to:

Whenever a tab is clicked, if there's a way to identify it (by <Tabs> id or groupId), put in the URL (w/ history replace state so it doesn't affect history) so you can just grab the URL from the address bar, and it links to what you're looking at.

[Josh-Cena]

Yes, another big part of the UX that I'm unsure of is when the querystring should be physically appended to the current location so it can be copied. I'm thinking about double-clicking but that's quite an implicit UX. Would appreciate it if anyone has an example of a site with this feature.

If no-one wants to take a shot, I'll probably work on this in July because I plan to use this ourselves for https://docusaurus.io/docs/deployment.

[lorensr]

I'd be happy with always adding on every single click. I don't remember any sites with this exact tab-maintenance feature, but plenty of apps edit the URL on each click so that you'll end up in the same state on reload or link copy/paste. A couple that come to mind are Gmail and Mint.

[slorber]

Also remember that we have to consider React hydration: on first page load, the correct tab must be selected even before React hydrates (ie you can't just useEffect, you also have to inline some JS to handle that, similarly to the dark mode)

What we don't want is to have the page load on a tab, and then switch to another tab 1sec later

[alliyya]

+1 for the desire for being able to link to a particular tab

Mildly related, but adding an id prop to the Tabs component would allow one to at least link to the whole set of tabs which I think is useful on its own and if there's a default/sync'd tab it's already open to the user.

[YOU54F]

Thank you @slorber 🥰cannot wait to try this out 🚀