Make headlines permalink-able

Let’s do whatever it takes to make it performant, non-obtrusive, intuitive, and accessible to link to headings. In today’s master the only way you can make a link to a heading is if you scroll up and find the TOC in the sidebar (on mobile it’s much more hidden).

Note! I think we should still keep the TOC tables in the sidebar.

There are two potential ways to do permalink-able headings. The way npmjs.com and github.com does READMES that there’s a little “chain icon” that appears to the left (or to the right) when you hover over the link.

Another approach is to simply turn every heading into a “self-link” like docs.github.com does. Example page The headings are basically like this:

<h3 id="enabling-github-dependabot-version-updates-for-actions">
  <a href="#enabling-github-dependabot-version-updates-for-actions">
    Enabling GitHub Dependabot version updates for actions</a></h3>

The advantages of that are that it requires 0 CSS and 0 JS to make it happen, and it works without a mouse device.

[peterbe]

Whatever we build, let’s not build a thing that requires some client-side JavaScript to mutate the DOM based on some query selectors.

[peterbe]

I definitely favor the way docs.github.com does it and I’m confident it can be done pretty easily with Yari since we control the HTML as a DOM (with cheerio).

I think it’s up to @schalkneethling and @malqinneh to decide and perhaps they prefer to push this out to the design system process.

But it might be worth it for the dev team (hi @escattone and @Gregoor ) to consider throwing this in now as an HTML thing and then mdn-minimalist can style it.

What do you think?