Replace AnchorJS with a Hugo render hook

[XhmikosR]

TODO:

• move the levels to config.yml
• a11y
• maybe use ::after?
• add padding?
• fix :focus if possible
• test that there are no regressions

Idea taken from gohugoio/gohugoioTheme#146

Pros:

• No JS
• ...

Cons:

• Works only with Markdown headings, but on the other hand our ToC only works with Markdown already
• ...

---

Preview: https://deploy-preview-32953--twbs-bootstrap.netlify.app/docs/5.1/getting-started/introduction/

[XhmikosR]

@mdo @ffoodd any thoughts?

[coliff]

heya - FYI- I used render hook code similar to this for a docs project and Algolia displayed the anchor # in search results window after the titles which wasn't ideal.
We changed it so that the # was displayed using ::after like you noted - so would definitely recommend you do that for a nicer Algolia search UX.
But other than that - I would recommend this approach. It works great and nice to not need JavaScript :-)

[XhmikosR]

@ffoodd could you help me out with this please? ❤️

[ffoodd]

I'll try to 👌

[ffoodd]

Seems already good to me!

What :focus fix did you have in mind? It's working fine IMHO.
There's no need to use a pseudo-element to handle # here because aria-label erases text content from link's accessible name.

So yeah, that's really good I think :)

[ffoodd]

aria-label value is questionable. @patrickhlauke Do we consider the heading context is enough, or should we try to complete the label using heading's content?

[patrickhlauke]

yeah i'd probably go for something a bit more descriptive, like having aria-label="Link to this section: {{ .Text | safeHTML }}" perhaps. yes, admittedly a bit wordy, but it front-loads what the meaning of the link is and AT users can always choose not to listen to the entire thing

[XhmikosR]

Note that I used what anchor.js is already doing. I don't have a preference about this, whatever you guys think is better.

[ffoodd]

Regarding this being markdown headings only: since this is outputs a very simple markup, we should be able to add anchors manually on markup headings, shouldn't we? It may even be a simple shortcode to help computing the markup.

[XhmikosR]

Seems already good to me!

What :focus fix did you have in mind? It's working fine IMHO. There's no need to use a pseudo-element to handle # here because aria-label erases text content from link's accessible name.

So yeah, that's really good I think :)

See @coliff's comment above.

Regarding :focus, I thought that we showed the anchor on focus but apparently we don't.

Regarding this being markdown headings only: since this is outputs a very simple markup, we should be able to add anchors manually on markup headings, shouldn't we? It may even be a simple shortcode to help computing the markup.

I think we should be OK in the sense that ToC already works with Markdown headings anyway. So, this way, we are actually more consistent, I think.

[ffoodd]

Made a few tweaks to polish this: improved aria-label after discussion, and (opinionated) made the anchor link visible when anchor is active (with :target).

Might help recalling the current URL targets an anchor, which I often forget about :D

Edit: also moved the # to a pseudo-element to follow @coliff 's recommendation.