Heading anchor links styling

[petesfrench]

Visual

Normal:

Hover:

Context

All docs

SCSS example

.p-anchor-link {
  color: $color-dark;

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

  &:after {
    @extend .p-icon--anchor;
    content: "¶";
    display: inline-block;
    padding: 1rem;
    top: 0.6rem;
    visibility: hidden;
    margin-left: 0.75rem;
  }

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

<h2><a class="p-anchor-link" href="#in-this-documentation-1" name="in-this-documentation-1">In this documentation</a></h2>

[danielmutis]

WG: @petesfrench @juanruitina to provide a couple of examples of how this has been implemented in other DSs and we could look into commissioning a design for the icon.

[juanruitina]

I've had a look at a handful of websites that have heading anchor links:

• All websites except MDN use the link icon (🔗). I suggest that we go ahead and commission that icon.
• Most just link to the heading as we do. Only Google's copy the link to the clipboard. ✅
• Only MDN and GitHub make the whole heading clickable as we do, most just make the icon clickable. But I don't think our approach does any harm.
• Most show the icon on hover as we do ✅
• Some show the icon to the left of the heading, some to the right. I'm not sure which approach is best, but it seems to the right is simpler, even if it can potentially result in wrapping. But maybe this requires some testing with real content.

Benchmarking

Discourse: icon to the left, shows on hover, only icon is linked, points to anchor

Carbon design system: same as Discourse

Apple Developer: same as Discourse (but icon to the right)

React documentation: same as Discourse (but icon to the right)

MDN Docs: hash to the left on hover, both heading and icon point to anchor

GitHub documentation: icon to the right, always visible, both heading and icon point to anchor

:

Material: icon to the left shows on hover, copies link

Google Cloud documentation: same as Material (unsurprisingly), icon to the right

[bartaz]

Gov.uk doesn't seem to use anchor links on headings. Headings have ids (so can be linked to), but anchor is only accessible via table of contents, not the heading itself.

https://www.gov.uk/government/news/bird-flu-avian-influenza-latest-situation-in-england#cases

[petesfrench]

@bartaz The request to have the headings clickable comes from the documentation team

[bartaz]

@bartaz The request to have the headings clickable comes from the documentation team

Yes, I know. We are just gathering examples of how others are doing something similar.

[juanruitina]

Hold on, we do have a link icon in the Figma library! It just doesn't seem to be implemented. Could we just add it to Vanilla? @lyubomir-popov @bartaz

[bartaz]

Hmm… we have the icon of that name, but it's a chevron… I can try to track down if that was a deliberate decision or just some mistake:

[bartaz]

We have the icon in code snippet component, it looks like a bug that it got replaced to chevon. We can bring it back.

[danielmutis]

WG: Link icon is a good fit.

[petesfrench]

@bartaz What do we have to do to get this upstreamed to vanilla?

[bartaz]

@petesfrench Create a PR and we can take it from there in review.

[bartaz]

It may be good to verify it first by some local implementation on one of the docs websites, to see if that works as intended in the context of the docs.