Table of Contents don't work using Tabs

[tmuskin]

🐛 Bug Report

Description

Some pages are using tabs to organize information using the documentation on tabs from Docusaurus. The table of contents on the side is generated, but when you click on any of the links in the table of contents only the headers which is under the tab that is open works the other links do not work or bring you to the correct tab and section of the page

Have you read the Contributing Guidelines on issues?

Yes.

Steps to reproduce

1. Create tabs in a doc by following this page
2. Create headers underneath multiple tabs
3. Generate the page and try to click on a link from the table of contents that is not a header on the tab that is open.

Expected behavior

The link in the table of contents would take you to the correct tab and section of the page

Actual behavior

The link does not bring you to the correct tab or section of the page.

Your environment

• Docusaurus version used: V2 beta 4
• Environment name and version: Chrome 92.0.4515.107

Reproducible demo

View CodeSandbox

1. Go to the Tab Bug page under tutorial
2. Make the view so that you can see the table of contents on the side
3. Try clicking on a tab then a link in the table of contents that is not in that tab

[slorber]

I don't think it's a good practice to put headings inside tabs, why would you want to do this in the first place?

Nobody ever came up with a need for this so this is more a feature request than a bug.

Unless you have a strong use-case for this and can explain why it's a good idea or documentation pattern, I would rather close this issue because implementing this is likely to encourage something that I consider an anti-pattern.

[Josh-Cena]

this is likely to encourage something that I consider an anti-pattern.

I would call this is a bug because things aren't working as intended. If headings in tabs aren't supported at all, we shouldn't index them in the TOC. Having them in the TOC while not providing correct navigation is bad UX

@tmuskin if you don't want the headings to be indexed you can use HTML <h2> and <h3> tags instead for now

[slorber]

Is there any example of this UX implemented correctly anywhere on the internet?
Or anyone has mentioned/discussed this UX pattern as something useful in some cases?
Or are we just discussing theory?

I understand that this may be considered a bug, but IMHO it's a bad idea, and solving this "bug" would only encourage a bad pattern + has very little ROI. The Tabs component is only provided as a convenience and the user remains able to implement its own tab component with MDX or use an external lib providing a Tabs-like feature that supports this pattern.

Unless it's clearer that this is something we really want to support, I'm not willing to work on this, and would rather only merge a contribution PR if this does not harm maintainability with additional complexity

---

If headings in tabs aren't supported at all, we shouldn't index them in the TOC.

Similarly, if user has <SomeComp/> in MDX that renders h2/h3 headings, but those headings do not appear in the TOC, I wouldn't consider it a bug. It's just something we don't want/plan to support for various reasons (little ROI, complexity, perf).

I think it's fair to not support all possible patterns like that, and I would only document the limitations.

[Josh-Cena]

Makes sense, thanks 👍 Agree that once the content is wrapped in components the page is not static anymore, and we are not in a good position to provide rich navigation

Similarly, if user has <SomeComp/> in MDX that renders h2/h3 headings, but those headings do not appear in the TOC,

Actually, the confusion is that these headings do appear in the TOC. But I agree that we probably can't help much, because removing them from the TOC sounds bad as well, considering use-cases like a simple wrapping box.

[slorber]

As soon as we introduce some React components in MDX (including user-provided ones) this opens the door to both cases:

• heading in toc, but not visible in page (ie in hidden tab, details collapsible...)
• heading not in toc, but visible in page

It does not seem worth it to support those edge cases and would be quite complicated to do so in a generic way. If someone really wants this, they can implement such logic themselves instead of asking us to do so.

Going to close for now, and see if someone can come up with a good reason to support this

[tmuskin]

We do have a use case, we have a long list of headers and information under each tab and need our users to be able to easily find each header without having to click on each individual tab to find the right one. Having the table of contents allows them to easily scan for headers and go to the one they need quickly. If clicking onto the table of contents header doesn't take you to the section then it defeats the purpose of the table of contents.

[Josh-Cena]

we have a long list of headers and information under each tab

@tmuskin What @slorber means is why you need headings under tabs. If you have very long tabs you may want to turn then into separate doc pages instead; if you think the TOC doesn't work well you can disable indexing these headings by using <h2> instead of ##

[nategoethel]

I also have a use case for this. In our product, there are different modes/views that change how the user interacts with the system. We use tabs to keep the mode-specific steps together rather than having what amounts to three separate pages for each mode.

We could use tabs inside each header section to reflect how to do X in each mode (e.g. Loading data with mode A, B, and C), but it's a much cleaner UI to have the tabs at the top of the page and have each tab effectively render as the full page for the user.

The problem for us is that the TOC simply takes each H1 - H3 and creates a link, so we end up with lots of duplicates:

We would appreciate a way to say "only show TOC links for what's on the screen," e.g. the current tab.

[Josh-Cena]

First off, it's impossible to have dynamic TOC, because the TOC is rendered statically during build. So the only way is to exclude everything from the tabs. See #6201 for more discussions.

[michaelcretzman]

this should be supported. Headings in Tabs are commonly supported in CMS's like Archbee.

Just because information is in a tab doesn't mean it should not have headings to categorize it.

if you have headings, they should be reachable by navigation.

Currently your tabs support headings, and adds them to the nav, but if you click a nav link for a heading in an infocused tab it is a dead link.

It seems impossible to believe this is working as intended as your nav does not work.

[slorber]

It seems impossible to believe this is working as intended as your nav does not work.

@michaelcretzman condescendence does not help

You underestimate the complexity of this feature that IMHO few people implement properly apart the Stripe docs:

(also discussed in #8591)

(note even mentioning the mobile UX)

---

Keep in mind that:

• You can implement your own theme
• You can implement your own Remark plugins to create a custom TOC
• We can now persist tab value in query string, this might help (new feature from feat(theme-classic): store selected tab in query string. #8225)

Docusaurus is flexible and allows you to build things by yourself. Docusaurus is open-source and you can submit a PR. You can also support the project on OpenCollective so that the core team has more bandwidth to work on such features.

[Zenahr]

@slorber are there plans on generating the TOC dynamically? From what I can tell, that seems to be the only bigger road block on this.

As for the use-case on this: I personally don't think it's an anti-pattern to offer headings under tabs.

In our docs, our software offers similar functionality for different types of users. One way of structuring this info is by feature->for user type 1; feature->for user type 2.

Example:

We have a doc on features surrounding security and safety. One topic on that is managing passwords. For managing passwords we offer several sub-features that differ between user types.

The reason for using tabs in this instance is to reduce uninteresting text. E.g., if I'm a user type 1 then I don't want to skim over the options provided to other user types. Tabs offer a nice compromise on that.
This is just one example of how this feature would help write better docs that are more comfortable to read. Just my 2¢ on the matter as a tech writer.

[slorber]

If anyone in the community builds a POC for this and is able to explain in depth what could be the impact in terms of React hydration, SEO, accessibility... we could revisit.

All that seems complicated for me to get it right and isn't a top priority for me to work on.

If you think it's easy to implement, then you can work on it 😅 good luck.

[slorber]

Seeing all those downvotes, I understand that many want this feature. However I stand by it is complicated to achieve for Docusaurus, notably due to its static nature.

---

Let's take a look at how Stripe implements it.

This page has different toc/headings depending on the selected tab (that you can pre-select through query-string)

• https://docs.stripe.com/elements/address-element/collect-addresses?platform=web
• https://docs.stripe.com/elements/address-element/collect-addresses?platform=ios

The initial page HTML only contains the pre-selected tab panel content, and not the other tabs.

This means that the Stripe docs are using server-side rendering to achieve that, which Docusaurus does not support. We have extra constraints that make this difficult to achieve. I'm curious to see if any static site generator has implemented such UX so far.

[kayx23]

if you don't want the headings to be indexed you can use HTML <h2> and <h3> tags instead for now

@Josh-Cena I'm adopting this approach; the only downfall is we lose the title anchors. Any tip for adding them back?

[slorber]

if you don't want the headings to be indexed you can use HTML <h2> and <h3> tags instead for now

@Josh-Cena I'm adopting this approach; the only downfall is we lose the title anchors. Any tip for adding them back?

@kayx23 the anchor is added through a custom theme component. You can either use your own custom component, or reuse the classic theme one.

import Heading from '@theme/Heading';

<Heading as="h3">My Heading</Heading>

Before Docusaurus v3 and MDX v3 breaking changes, using <h3> would automatically render the theme heading component we provide. After v3, you now have to use this component manually in your MDX (MDX requires you to be more "explicit").

[kayx23]

Thanks for the reply @slorber. We are using v2. When I used <h3>xxx</h3> directly within tabs, the anchors did not show up.

I also tried your suggestion to explicitly import and use <Heading as="h3">xxx</Heading>. It did not add the anchor either.

[slorber]

@kayx23 in case you misread, it is expected that the anchors do not appear in the TOC in such case.

if you don't want the headings to be indexed you can use HTML <h2> and <h3> tags instead for now

We don't provide a solution to make tab headings be indexed in the TOC atm.

[TomerAberbach]

Just wanna add my use-case in case it helps with prioritization :)

I have a table of contents that looks like this:

I was hoping to:

1. Be able to wrap the headings under "How do I use it?" in a <Tabs><TabItem value='sync' label='Sync'>...</TabItem></Tabs>
2. Add an additional <TabItem value='async' label='Async'>...</TabItem> that has slightly different, but related/associated headings:
   • AsyncFunctionReducer
   • AsyncOptionalReducer
   • AsyncReducer
   • AsyncKeyedReducer

Basically, I am documenting a feature of a library that has a sync and async version of each type. I thought it would be a bit verbose for the page to have the sync and async stuff sequentially, especially when each type has a sync and async version. It would be nice to allow users to quickly switch everything under this heading between sync and async using tabs.

I think my workaround at the moment will be to name the headings like so:

• FunctionReducer and AsyncFunctionReducer
• OptionalReducer and AsyncOptionalReducer
• Reducer and AsyncReducer
• KeyedReducer and AsyncKeyedReducer

And add "Sync" and "Async" tabs under each heading (with group ID to keep the tabs across headings synchronized).

This seems reasonable to me so I'm not too torn up about this limitation, but just including this use-case in case it sways anyone!