Linked content tabs

[2bndy5]

Well, it looks like linked content tabs will remain an insiders feature only. Originally, I thought the feature would get included in the public releases when the upstream funding goal hit $5000+, but the linked tabs feature wasn't made public when that goal was recently met.

So, we have to implement linked tabs ourselves.

Implementation

I envision this as a :linked: option to the md-tab-item directive. This could be a flag (option accepts no value) or an option that expects an identifying string.

• Expecting a string value would align with sphinx-design implementation and allow for linked tabs to have different labels.
• A flag might be easier from the user's perspective (relying on commonly shared tabs' labels), but that may be error prone. For example, case sensitivity or non-text elements in the linked tabs' labels.

[jbms]

Should the :linked option be just on the md-tab-item directive or on the md-tab-set directive as well?

I can see how it would be useful to specify an identifier for a non-text label (although for accessibility it would probably be good to have a text label as well even if you want to display an icon), or as an override, but it seems like in almost all cases you would just want to mark an entire tab-set as linked (and use the text of the tab label as the key).

In the same case, you link multiple tab sets that all have the same set of labels. In that case it is pretty obvious what the behavior should be --- their selected tabs should remain the same at all times.

However, it is a bit trickier if some tabs are linked but not others.

For example, suppose the tab labels correspond to programming language, but not all tab sets include all programming languages. E.g. first tab set has "C", "Java", "Python" and the second one has "Java", "Python", "JavaScript". Presumably if we select "Java" or "Python" in one we want it to be selected in the other. If we select "C" in one --- presumably the other remains unchanged. So we would need to choose a representation in localStorage (https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) that accommodates that. Perhaps store the last-selected-timestamp for each linked tab key.

[2bndy5]

Glad to see you're already thinking about the implementation details. Since I'm not a JS expert, I'd probably look for inspiration from similar implementations (like sphinx-design ext).

Just to throw it out there, sphinx-design also supports a special directive aimed at linking tabs based on specified syntax.

I think we can support a linked option with and without a specified value:

1. without a specified value relies on the tab's label (astext())
2. use a specified value as a key which may correspond to another linked tab's label (whose linked option has no specified value).

It does make sense to let md-tab-set control the contained tab-item's linked option (wouldn't be difficult). Although, a linked option for the entire tab-set should not expect (or use) any specified value (as a linking key would only apply to 1 tab).

As for accessibility, I don't think this is high priority on upstream (table type code-blocks with line numbers are non-default in sphinx for this reason - inline line numbers are default for screen readers and such). I'm not saying to ignore it, but it would be nice to also accommodate accessibility standards also.

[2bndy5]

In response to #111 (comment)

Awesome! I didn't see that in the release notes. Currently, we're pinned to v8.2.8, but I can adjust our RST ext (concerning content tabs) as soon as we do another merge-from-upstream.

[2bndy5]

So, we have to implement linked tabs ourselves.

This no longer accurate. This should be resolved by #171 because there was no need to alter the content tabs' directives. 🚀

[2bndy5]

I started a discussion in mkdocs-material about exempting tabs (or tab sets) from being synced.

[2bndy5]

I got a response in the discussion. Ultimately, there isn't a way to specify an unique attribute/class/option to content tabs in MD. There is currently a significant ongoing effort to introduce a directive syntax that was inspired by MyST syntax, but the current MD syntax in mkdocs is a bit too mature at this point to expect users to instantly switch to the new directive syntax (if/when it finally goes mainstream).

Conclusion

We'll have to diverge a bit from upstream JS to allow exemptions/exceptions about linked content tabs (or entire tab sets).