Deep linking to individual tabs

[eric-schneider]

There are several use-cases where we'd like to be able to deep link directly to a tab (or nested tab). For example, we'd like to be able to link directly to a particular client example (or even a nested tab within that client example).

For ease of use, the implementation should leverage the existing approach to creating anchors in AsciiDoc. There are a couple of open issues in the Asciidoctor Tabs project that appear to relate to this requirement:

• Promote explicit ID on tab asciidoctor/asciidoctor-tabs#57
• Make default tab selection configurable asciidoctor/asciidoctor-tabs#58

We should do a holistic assessment of the technical requirements and determine whether certain parts of the implementation should depend on the extension itself rather than our own custom code. If we do our own custom implementation, there’s a chance that it might not play nice with future updates to the official extension (it’s still in beta, after all). If we determine that we are indeed dependent on upstream enhancements, we should probably open an issue in the Asciidoctor Tabs project (and/or comment on the existing issues noted above) to discuss our findings with the maintainers and potentially contribute the necessary enhancements.

[colegoldsmith]

@eric-schneider @djsauble I dug into the extension source code a bit and discovered it does have the ability to customize the id of the tabs block, and prefixes that custom id to the individual tabs.

Without a custom id the the extension generates tab ids like tabs-4-python which we can link to.

Using that client example, if we add a custom id install to the tab block like so

[tabs,id=install]
======
Python::
...
TypeScript::
...
Java::
======

The tab ids become install-python install-typescript install-java and we can create a direct link like url/astra-db-vector/get-started/quickstart.html#install-java

Conveniently linking to the individual tab does open it correctly and even opens all other linked tabs. There are a few issues remaining though:

• The auto scroll doesn't go down far enough and the tab text is covered by the header. This should be an easy fix with the scroll-margin-top css property.
• Linking to a nested tab does not open the parent tab(s). I could probably do this with some custom js by searching for tab ids when an anchor link is present but it would be a bit of a hack and like you say might break with future versions of the tabs extension.

Is linking to the top level tabs like this a good enough solution?

[djsauble]

This is great news, and yes I think as long as we can link to top-level tabs, that's likely a good enough solution for now.

Personally, I think nested tabs are a bit of an anti-pattern, so I'd like to avoid them where possible anyway.

[eric-schneider]

Agree that we should avoid nested tabs when possible. Though, there are some complex procedures (e.g. Cassandra upgrade) where nested tabs are the only viable option to maintain flow while still presenting the breadth of possible options.

@colegoldsmith, what's the pattern for nested tab IDs? Is it simply tabsetID-tabID-nestedTabID?

Also, what's your take on the two issues I linked? Seems like they're actually unrelated to what we're trying to achieve here, except that maybe we might not have the ability to set custom IDs on individual tabs. Also, neither issue seems appropriate for requesting support for deep linking to nested tabs. Do you think we should open a new issue for that in the upstream project?