Adds anchor links to headings

[petesfrench]

Only merge once Vanilla 3.14.0 drops

Done

• Adds def to add anchor links to headings similar to what they have on https://developer.mozilla.org/en-US/docs/Web/CSS/visibility#try_it (for example) NEW DEMO https://github.com/canonical/ubuntu.com/pull/13989

QA

• Go to https://ubuntu-com-13989.demos.haus/ceph/docs
• hover a link and see it underlines and a anchor tag appear next to it, see https://staging.vanillaframework.io/docs/patterns/links#anchor-link
• click the link and make sure it is appended to the url

Issue

https://warthogs.atlassian.net/browse/WD-8606

[sparkiegeek]

FWIW Discourse itself already has anchor links for headings, and CSS that makes it work.

Go to a docs page in Discourse and hover over the headers, you'll get a floating anchor appear.

e.g. https://discourse.maas.io/t/maas-documentation/6662/2#navigation-3

[petesfrench]

@sparkiegeek Yes, it's available directly within Discourse. However, this is the Discourse module which we use on our documentation sites, such as https://microk8s.io/docs/howto-addons. There, you will find that this functionality does not exist.

[sparkiegeek]

@sparkiegeek Yes, it's available directly within Discourse. However, this is the Discourse module which we use on our documentation sites, such as https://microk8s.io/docs/howto-addons. There, you will find that this functionality does not exist.

I am familiar with this module.

So, take a look at the Discourse HTML, you'll see e.g.

<h2 dir="ltr">
<a name="how-to-use-microk8s-addons-1" class="anchor" href="#how-to-use-microk8s-addons-1"></a>How to use MicroK8s addons</h2>

Now look at the corresponding generated docs HTML and you'll see...

<h2>
<a class="anchor" href="#how-to-use-microk8s-addons-1" name="how-to-use-microk8s-addons-1"></a>How to use MicroK8s addons</h2>

which of course is used by the (new) ToC on the right hand panel.

[petesfrench]

@sparkiegeek I think there is some misunderstanding on what problem this addresses, there is more information in the original issue: https://warthogs.atlassian.net/browse/WD-8606

[sparkiegeek]

@sparkiegeek I think there is some misunderstanding on what problem this addresses, there is more information in the original issue: https://warthogs.atlassian.net/browse/WD-8606

something like this

h1:has(a.anchor), h2:has(a.anchor), h3:has(a.anchor), h4:has(a.anchor), h5:has(a.anchor), h6:has(a.anchor) {
  color: $color-dark;

  &:visited {
    color: $color-dark;
  }

  &:after {
    content: "¶";
    display: inline-block;
    visibility: hidden;
    margin-left: 0.5rem;
  }

  &:hover {
    &::after {
      visibility: visible;
    }
  }
}

with no change to the HTML will give a similar (styles can be tweaked for perfection) behaviour to the one expressed in https://github.com/canonical/microk8s.io/pull/642

My point is that the HTML already contains everything that's needed, and it's simply a matter of styling.

[petesfrench]

@sparkiegeek this can work for regular users but will raise accessibility concerns as there is now an empty link in the page which will still be read by screen readers. You can look at MDN docs as an example (a site known for good accessibility practices)

[sparkiegeek]

@sparkiegeek this can work for regular users but will raise accessibility concerns as there is now an empty link in the page which will still be read by screen readers. You can look at MDN docs as an example (a site known for good accessibility practices)

Ah, cool - where's the corresponding Discourse bug?

[petesfrench]

@sparkiegeek I wonder if that is the intended behavior on discourse, as it is only the symbol that is clickable. Whereas on our documentation sites, we want the whole link to be clickable. I will raise a bug to get theie feedback and reference the work here.

[petesfrench]

@juanruitina This is the one, let me know if the QA instructions are not clear.