Add anchor links to headings for easier sharing

[NickColley]

Resurrected some old work...

When consulting the GOV.UK Design System I often want to link to a section that I'm looking at to help someone else so end up inspecting the source to get the id for the section.

This pull request allows you to click on the heading and be anchored to that section quickly.

This mirrors the functionality that exists in the GOV.UK Technical Docs format (https://tdt-documentation.london.cloudapps.digital/).

Main difference with this approach is that these anchors are exposed to keyboard users, whereas the Tech Docs format chooses to hide them. I chose to include them because keyboard users should also have an easy way to link to sections. There is a risk however of more links that could contribute noise for screen reader users looking at all the links on the page, so this should be considered in the review.

[netlify]

✅ You can preview this change here:

Built without sensitive environment variables

Name	Link
🔨 Latest commit	c361368
🔍 Latest deploy log	https://app.netlify.com/sites/govuk-design-system-preview/deploys/64b51172549d4e0008942698
😎 Deploy Preview	https://deploy-preview-2481--govuk-design-system-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[colinrotherham]

Hi @NickColley

Sorry this hasn't been looked at yet, I've added the awaiting triage label so we can take another look. We extended the marked Markdown renderer recently in c3afcd6 which would be a good place to extend

Will tag in @36degrees too as I know you've both worked on JS anchored headings in the past

alphagov/tech-docs-gem@2c4ff7e
alphagov/tech-docs-gem@327fb9a

They're not all indexed, but a useful tip can be to link to headings via the search

[NickColley]

Updated the branch to use the newer renderer code you've added.

[christopherthomasdesign]

Thanks for raising this again @NickColley, I remember talking to you about this idea years ago!

I think most people on the team think the use case for this is clearly there, and it's especially handy for people on our team doing support.

I had a few design / accessibility questions when looking it it just now. These are more reservations than absolute blockers, but would be good to get people's thoughts on:

• is it an issue that the functionality is only visible if you hover or focus on the headings? ultimately these are links, and by default they're not styled as such
• does the link icon clearly indicate what clicking on the link will do? is it even necessary to show an icon if the link underline shows on hover?

I'm also wondering if you could make it automatically copy the URL to your clipboard upon clicking the link, to save a step. Though that might need a different icon. And it could mess with people copying and pasting other stuff if it wasn't clear what it was doing.

[NickColley]

is it an issue that the functionality is only visible if you hover or focus on the headings? ultimately these are links, and by default they're not styled as such

Yeah I also worry about this, it feels like fundamentally a bit of a weird thing to have anchors in headings, and a compromise being made to solve (what I think) a valid user need. You could have the icon always being shown or a 'share' or something next to each header but it just felt like a lot of noise - which I'll admit is biased towards aesthetic.

This approach that hides the functionality until you interact is similar to how GitHub markdown works but that doesnt mean it's the best way or right way to solve the problem.

does the link icon clearly indicate what clicking on the link will do? is it even necessary to show an icon if the link underline shows on hover?

Yeah it seems unnecessary in this implementation... we could remove it.

I'm also wondering if you could make it automatically copy the URL to your clipboard upon clicking the link, to save a step. Though that might need a different icon. And it could mess with people copying and pasting other stuff if it wasn't clear what it was doing.

Interesting idea, I agree would need to be a clear interaction as at the moment the interaction is telling the user 'I'm a link'.

[NickColley]

It'd be good to get @davidc-gds 's thoughts on this approach since it is not your typical feature.

[NickColley]

Here's idea on what if you made it super duper boring:

Accessible name would need to reference the heading next to it otherwise you'd have many links with the same name.

Screenshots

Above

Below

To the right (easier to miss for magnified users)

To the right most (very easy to miss for magnified users?)

[NickColley]

Just feels like a lot to have next to every single heading is all.

Example on the right:

[dav-idc]

I haven't reviewed this fully at all, but just wanted to note how the W3C handles permalinks on their guidance documents, in case it's a useful reference:
https://www.w3.org/TR/WCAG22/#content-on-hover-or-focus

They seem to use a § symbol in a :before pseudo element on a link. Then the link itself has a label reading: aria-label="Permalink for Section 1.4.13"

[NickColley]

Here's how it'd look if they're always visible like David's example

[NickColley]

@davidc-gds interestingly their implementation doesnt meet contrast requirements so I wonder the last time they reviewed it:

https://webaim.org/resources/contrastchecker/?fcolor=91B0CF&bcolor=FFFFFF

[owenatgov]

Adding onto the discourse, I gave this a quick test with voiceover. As has been articulated already, all non-h1 headings are now links which is show visually with the link styles and the icon on the left and are declared as links by VO. When activated, the address bar changes to reflect the anchor link and there's a little navigation chime but the page obviously doesn't navigate and VO announces the heading again (probs because the anchor link just refocuses on that same heading).

My reckon here is that the screen reader experience could be confusing since "nothing happens" and there's no context. I personally like the idea of separating the functionality into a link (I like the one below the heading in your ideation above, Nick) and/or using an aria-label. I was initially thinking adding some hidden text to the end of each heading to add context for what it does, but I think I prefer the other solutions presented in the PR comments so far. The copy idea is also neat but I reckon a link might be simpler.

Some final thoughts:

• I really like this idea and hope we can get this contribution in. I find I do section specific sharing al ot and making it less of a hassle would be super cool.
• Considering we're putting this PR through the ringer, I'd like us to contribute whatever solution we agree upon back to the tech docs gem.

[CharlotteDowns]

Adding in some additional issues for extra context:

• Make it easy to link to sections of a page #425
• Difficulty linking to headings within the Design System website pages #1390

[christopherthomasdesign]

Potential can of worms this, but occurred to me that another approach could be to introduce in-page navigation at the top of each relevant page.

I've put it in a details here cos if you include all the headings it gets really long on some pages. As you can see, it then starts to clash with and duplicate the nested in-page navigation on the left:

So maybe it'd replace that nav on the left. Arguably a better separation of concerns, having navigation for pages separate to in-page. Maybe.

The good things about this: it'd avoid the issues with having hidden links within headings, using ambiguous icons, or having repeated 'Link to this section' links all over the page.

On the other hand, it's not as obvious an interaction for the use case we're discussing here. Or as immediate. You'd have to go back to the top of the page, click the link, then copy from the URL in the address bar. Still easier than inspecting element though.

And like I said, it affects other aspects of the site, which might just be too big a change to make without testing anything.

[colinrotherham]

@NickColley I've rebased this as we'd caused a few conflicts for you

[NickColley]

@colinrotherham I think this work is somewhat blocked as I don't have the authority to say what direction it should go from a design point of view, so I think the team should come up with their prefered way forward and I can get that ready to go. If the team is currently really busy then maybe we close this out for now until there's time.

[stevenjmesser]

Removing from active sprints until there is capacity to work on it. Needs design input. Related to website changes or service design for the design system, which isn't currently a prioritised objective.