search

konstructio / kubefirst-docs

kubefirst documentation
https://kubefirst.konstruct.io/docs
MIT License
6 stars 8 forks source link

Double side TOC for GitHub/GitLab tabs headers #736

Open fharper opened 2 months ago

fharper commented 2 months ago

What type of suggestions?

Something's not working

What page is concerned?

https://docs.kubefirst.io/aws/overview

What version of the docs?

2.4+

What is the issue?

In all documentation page where there is a GitHub/GitLab tab with the same header (the content structure of those are usually the same), Docusaurus display the two headers on the right side of the page, and not the one only visible. That wouldn't be such an issue if Docusaurus was able to display the right tab if you click on the header of the unfocussed one (we could have giving them specific name), but it's not. So it doesn't look good, and it's not totally functionnal.

https://github.com/user-attachments/assets/47e30f4e-d1ad-41c8-b4e6-f27098f1d86e

Code of Conduct

fharper commented 2 months ago

Not critical, but it doesn't look good.

fharper commented 2 months ago

So there is no way to prevent this as Docusaurus isn't dynamically creating the TOC at runtime. The "solution" is to either

  1. remove the headers from tabs (which would go against why we use them—to deduplicate content),
  2. use HTML tags for headers inside the tabs so Docusaurus won't use them in the TOC.
  3. remove the right side TOC entirely.

Option one is going against why we use tabs, which is to minimize duplicated content. Option two make the TOC working differently depending on the situation, so not ideal: it will also be a PITA to remember to use HTML element vs Markdown for headers when inside a tab. Option three is the most clean in terms of keeping the same experience everywhere, but it will remove a TOC that may be useful for the users to find the content, so really not the best option here.

See https://github.com/konstructio/kubefirst-docs/pull/743 for more information.

It's not that critical as an issue, but it doesn't look professional as the TOC is something that should be quite simple to manage. In addition to that, the TOC item only work for the content displayed in the actual select tabs. Let's say I selected the GitHub tab, like in the screenshot from the initial issue comment, if I click on the first Application the browser will move to the proper anchor. If I click on the second Application, which is the one from the GitLab tab, if GitHub is selected, it will do nothing, caused the header is not visible. So it become non-useful.

Really not sure what to do here (option #2 seem the most "appropriate"), so thinking out loud if anyone has any ideas or preferences.

For now, I'll leave it like this unfortunately.