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.