[docs] Update the styling of the TOC

[mbrookes]

• I have followed (at least) the PR section of the contributing guide.

This is a good page to compare the before and after:

• https://next.material-ui.com/style/icons/
• https://deploy-preview-14520--material-ui.netlify.com/style/icons/

In addition to the change of styling (updated again since first commit):

• Smooth scrolling (removed out of consideration for those subject to motion sickness.)
• Add the current hash to the URL (subject to ongoing discussion) (Merged to get user feedback. Might be removed for v4.)
• Fix an issue where the current logic selects the next section when you scroll past a heading.
• Fix an issue where the correct TOC item is not selected when clicking '#' links near the bottom of the page.
• Fix an issue where the correct TOC item is not selected when clicking TOC links for sections near the bottom of the page.
• Remove an unneeded call to findActiveIndex() in componentDidMount().
• Fix a duplicate id (font-awesome) on http://localhost:3000/style/icons.

[mbrookes]

This started as a quick restyle of the TOC, and escalated from there!

[oliviertassinari]

I'm trying to find examples of great documentation. Few have a TOCs: developers.google.com, getbootstrap.com, docker.com, most don't have it. After looking at them, I think that we should keep the current logic:

• The TOCs collapse creates a distraction when reading the documentation.
• The TOCs collapse prevents to see all the subsection up-front.
• I don't have any strong case against the hash change based on the scroll. But given none of the documentation I could benchmark do it, I would rather not do it either (maybe I have haven't looked at enough documentation 🤔). Just so people have a consistent behavior between the different documentation they have to browse when working on one project.

One thing I think that we should work on regarding the TOCs: i18n support, it's quite a broken right now in Chinese ✌️.

[mbrookes]

none of the documentation I could benchmark do it

Here's one you might be familiar with! 🤣
https://material.io/design/components/app-bars-bottom.html

Doing this means that when someone is referencing the documentation, the URL pinpoints the specific section. (If anything, it bugs me when there isn't a specific enough id. Having to say "go to this URL, then scroll down to XXX is a PITA for everyone.)

(Yes, we have the '#' icon, but it's easy to miss, or to forget to click before copying the URL.)

[mbrookes]

Maybe add numbers to the indentation to make the distinction between section and subsection clearer?

At one point I had ' - ' in front of subsection titles, but because of wrapped headings, it looked odd, so I dropped it (although there is almost certainly a CSS solution to that which preserves the indentation for subsequent lines).

Perhaps rather than making the currently selected section or sub section bold, we reserve it for top level sections. The highlight should be enough by itself to show the currently selected section, so long as contrast doesn't suffer without the emboldening.

[oliviertassinari]

Here's one you might be familiar with! 🤣

@mbrookes I shouldn't have said "none" :). Then maybe it's just me spending too much time on their documentation, I dislike the way it's structured. They have disabled the headlines click to get the anchor. Yeah, I think that we should use this documentation as an example of what we shouldn't do 🙆‍♂️. I'm curious on the ratio % count of docs website using manual anchor links vs automatic. As somebody often linking documentation anchor, I personally prefer "being in control".

Doing this means that when someone is referencing the documentation

Then why so few documentation websites use this approach? I think that it's because you don't know if a person is going to link the whole page or a subsection, you let him choose. Most of the time, they link the whole page, so you optimize for the majority. It's also an incentive for us to split large documentation pages.

I would need to manually click through those to find the part I'm interested in.

@eps1lon 💯

---

IMHO we shouldn't try to put too many thoughts into how the TOCs work. I think that a lot of documentation, older & more used than our have spent a lot of time on the problem, I would just copy what the majority do. "The majority is right", I think that it applies in this case. It's what I have tried to do when implementing the TOCs.

[eps1lon]

Doing this means that when someone is referencing the documentation

Then why so few documentation websites use this approach?

To be fair: This is probably skewed because it's the default behavior of the docs software.

I think having the anchor automatically update is a nice feature. It doesn't require knowledge about position of anchor links or if one even exists. I would even prefer if the anchor links where visible by default.