Some questions regarding tabs

[ColonelPanics]

I've just found retype today and it's exactly the documentation solution I was looking for. It's so easy to use, doesn't overcomplicate markdown (as I've seen some other "markdown" doc tools do) yet still provides neat extra features for improving documentation.

I am, however, finding myself a little stuck with my usage of tabs. Here is my scenario:

• I have a page describing a process that has a tab for different destinations the process can be followed for
• These tabs contain a few headings for different parts of the process
• Some tabs contain a process which is external/unsupported, in this case I'd also like to provide a link to a similar (but supported) tab

Issues I've hit:

• The sidebar contents for the page only apply for the default tab, despite my header names being the same in all the tabs, I am unable to use the sidebar to navigate to that section of a different tab
• If a tab has a link to another tab's anchor within it, clicking it updates the url but none of the content (the tab is not actually switched to)
• If I separate the documentation to have a header for each stage of the process and have tabs underneath each of these I can then navigate the page to the specific part of the process although it requires selecting the non-default tab for a specific destination in each section

Perhaps some feature requests:

• Some sort of way to allow selecting all tabs with the same name on a page (this would also be handy for code examples, if there were many examples for python, ruby, etc on one page, you wouldn't want the user selecting ruby on each example)
• Dynamically updating the sidebar for selected tabs
• Allow tabs to link to different tab anchors in the same document
• Toggle to matching tag names in all tags on page when one is selected

Am I perhaps approaching tab usage wrong here?

I suppose I could separate each process out into its own page but unifying them as they follow a similar workflow (albeit it with slightly different commands per destination) seems like this is the right sort of thing to use tabs for.

I'd appreciate any feedback/thoughts on the above! 😊

[geoffreymcgill]

Hi @ColonelPanicks.

I've just found retype today and it's exactly the documentation solution I was looking for. It's so easy to use, doesn't overcomplicate markdown (as I've seen some other "markdown" doc tools do) yet still provides neat extra features for improving documentation.

Awesome! Thanks for the feedback.

Do you have a .md sample we could use to test with the scenarios above? just to ensure we're all looking at the same thing. Or, a link to a github project with your documentation files.

Linking to one Tab from another Tab should be possible, although I cannot remember if we specifically tested that scenario. We should certainly be able to get it working though.

Your point about not generating the sidebar table of contents for the Tab contents is a good one. We will test to see what's going on. Your .md sample would be helpful.

[ColonelPanics]

There is a sample of my first use case scenario at https://github.com/openflighthpc/openflight-docs/blob/framework/retype/stack/deploy-stack.md, this is also "live" (albeit in a staging fashion - still PoC-ing) at https://docs.openflighthpc.org/stack/deploy-stack/.

There aren't links between tabs in the .md at the moment because local testing didn't get it working so I opted to put a message in some tabs (e.g. the Omnia and StackHPC OpenHPC ones) to suggest switching to another. When I did add the links to other tabs I tried:

[this tab](#openflight-omnia)

and:

[this tab](deploy-stack.md#openflight-omnia)

But neither switched.

[geoffreymcgill]

Thanks for the sample. We should be able to get this all working, although it might some time. We're juggling the development of some big features, but will try to get this Tab issues solved as quick as we can.

The good news is that you will likely not have to do anything from your side. The Tab functionality should automatically just start working better with the future release when you update your site. If you leave those anchor links in your docs, they might not work now, but they should in the future.

[ColonelPanics]

Thank you so much @geoffreymcgill! I'm well aware of the 1.12.0 development (and I'm particularly excited for the introduction of partials!) so appreciate the time to consider this. For now I don't feel like the tab issues are complete blockers to using this tool and getting my documentation live.

Great to hear that future releases will likely just get this working!

[geoffreymcgill]

Some sort of way to allow selecting all tabs with the same name on a page (this would also be handy for code examples, if there were many examples for python, ruby, etc on one page, you wouldn't want the user selecting ruby on each example)

Interesting suggestion. We should be able to get this working. Figuring out what a clean url anchor and configuration should be is likely the most challenging task.

[ColonelPanics]

I haven't looked too much into what happens when there are multiple tabs with the same name on a page but I imagine the anchors either end up identical or appended with an index?

In the case that all tab sections have identical sections then could the anchor be shared for all of them? 🤔

[geoffreymcgill]

Dynamically updating the sidebar for selected tabs

Yes, this should be possible. Maybe a bit tricky to get this working, but definitely possible. The table of contents for each page is currently being dynamically generated based on the actual page headings, so we would just need to trigger a re-calc on a Tab change.

[ColonelPanics]

It may just be that I'm not going about using this correctly! I'll also admit that the tabs having the same headings within them may cause extra complications for navigation.

[geoffreymcgill]

Toggle to matching tag names in all tags on page when one is selected

Again, this should be possible. Interesting idea. I need to think about how we could make this work cleanly. Automatically matching the Tab labels would theoretically be enough, but there may be unintended consequences and scenarios where this behavior would not be desired. Then we need an option to disable, which I would rather avoid.

How about if it only syncs the active Tab on other Tab components when all the Tabs in the other Tab components have the exact same labels?

Tabs	Sync?
Red / Green / Blue	✅
Red / Green / Blue	✅
Red / Green	🚫
Red / Blue	🚫

[ColonelPanics]

Good spot on the use case that wouldn't go with the suggested behaviour.

I like it as an opt-in feature to not effect the default/expected behaviour, it would definitely suit my use case but now I'm wondering if there's perhaps a different/better way for handling my use case outside of tabs.

[DannyBen]

...but now I'm wondering if there's perhaps a different/better way for handling my use case outside of tabs.

Since you asked... :)

I took a look at your live retype site, and I feel like you better off avoiding tabs in this case completely.
It seems like you are looking at retype tabs as a navigational aid, while they were clearly not designed as such.

In addition to the problems you already encountered, here are a couple more problems I see:

1. The documentation site is not mobile friendly. Retype does not change the representation of tabs in a narrow screen.
2. It is not scalable. 5 tabs already feels too cramped. In case you have another process to add, you are doomed.
3. Although I am not familiar with the subject matter of in your docs, I am assuming most of the users will favor one implementation over the other - so having the other tabs is just noise for them.

My humble suggestion is this:

1. In your case, convert each tab to its own page
2. Use retype tabs for small snippets of code, or other small pieces of information that make sense as a group.

But, out of this, Retype can perhaps extract another feature request: Make tabs mobile friendly. There are multiple ways to do this, and if it is desired, we can extract to a new discussion.

[ColonelPanics]

I appreciate the feedback and had an inkling that pages would be the way forward. Thanks for having a look into it all!

[geoffreymcgill]

Make tabs mobile friendly.

@DannyBen By mobile friendly, do you mean when the combined width of the Tabs stretches beyond the width of the viewport?

Here's a (mega-super-high-res) screen capture of the Tab from my iPhone:

If the label width of the Tabs and/or the qty of Tabs is reduced, then all the Tabs are rendered correctly on mobile and the mobile UX seems to work well.

If the Tabs stretch beyond the viewport width, then we could collapse the non-visible Tabs into a drop-down menu on the far right of visible Tabs. I think we had originally planned for this functionality, but just never had the pressure to implement.

[DannyBen]

By mobile friendly, do you mean when the combined width of the Tabs stretches beyond the width of the viewport?

Well, yeah. Any vertical element, such as tabs or tables, need to have special treatment in a responsive design.
Right now, it seems that tabs are not getting any special treatment, so they will exceed the intended width and corrupt the page design.

Easy to view how they behave poorly in responsive mode in Chrome dev tools.

There are multiple ways to solve this on mobile, is there an open feature issue / discussion we can use? I don't want to hijack this one.

(and I agree, it is not necessarily a top priority).