Add self links next to headings that have ids

[jean-gui]

To help linking to a specific part of ecosystem pages, @koalie manually added self links next to some headings, for example https://www.w3.org/ecosystems/publishing/#groups.

It would be good to generalize this with Javascript to automatically add self links next to headings that have an id. Some styling work would also be required to make those links a bit more subtle, as on https://www.w3.org/2023/Process-20230612/#Intro or https://attacomsian.com/blog/deep-anchor-links-javascript for example. Note that the latter doesn't work well on touchscreen as it appears when hovering the title.

[NicolaSaunders]

@jean-gui It looks like there is a free Craft plugin specifically for this: https://plugins.craftcms.com/anchors?craft4

I would advise giving this a go. Handling this via the PHP should be more performant than using client side JavaScript.

[vivienlacourba]

@jean-gui It looks like there is a free Craft plugin specifically for this: https://plugins.craftcms.com/anchors?craft4

I would advise giving this a go. Handling this via the PHP should be more performant than using client side JavaScript.

As we use Craft in an headless mode would that plugin work?

Also for pages not coming from Craft (e.g. pages coming directly from our Symfony main application or pages written manually) I guess we would need another solution (or maybe a complimentary one).

[simonrjones]

@vivienlacourba is right the Craft plugin is unlikely to work in Symfony. We would need to test to be sure, but from what I can see the code isn't a standalone Twig filter.

Can I clarify the functionality you're looking for? Is it to only create named anchors in headings that have manually set IDs? Or to create anchors on all headings in the text? I believe the Craft plugin parses all headings to create anchors.

And to confirm, you don't want any links at the top of the page to headings (such as a table of contents)?

As you note this would also need some styling work.

[vivienlacourba]

@vivienlacourba is right the Craft plugin is unlikely to work in Symfony. We would need to test to be sure, but from what I can see the code isn't a standalone Twig filter.

This possibility should to be available anywhere we use the design system independent of the platform. Today we generate pages using Symfony on the frontend and main apps, but we anticipate using it on manually crafted pages or pages built from any language (we do have other apps in plain PHP, Perl, Java and even C). Hence @jean-gui's initial proposal of using Javacript for this functionnality.

Can I clarify the functionality you're looking for? Is it to only create named anchors in headings that have manually set IDs? Or to create anchors on all headings in the text? I believe the Craft plugin parses all headings to create anchors.

Only the ones that have an id.

And to confirm, you don't want any links at the top of the page to headings (such as a table of contents)?

Correct.

I believe the "self links next to headings that have an ID" and "table of contents" are two distinct features.

I think we would want the former to be available everywhere, whereas "table of contents" probably only make sense on long pages and should remain an optional feature that the page author decide to include or not.

As you note this would also need some styling work.

Yes.

[NicolaSaunders]

For further clarification, there is no need to create the id on the heading - just the anchor link itself for any heading with an ID?

It would be more robust if the anchor markup was handled on the server side rather than with client side JavaScript. It means the functionality will always be there, even if the JavaScript should fail for some reason. I also worry a little about the front end performance, if there is a long page with a lot of headings requiring the creation and insertion of an anchor.

The current manual implementation could be improved for accessibility. The anchor link does not have an accessible name - the symbol is announced as "Section symbol" in Safari with VoiceOver. I recommend that the symbol is contained within <span aria-hidden="true"></span> to stop it being announced by screen readers, and another <span class="visuallyhidden"></span> is added inside the anchor to hold the accessible name of the anchor link. This can be as simple as the word "anchor".

This does also raise the subject of internationalisation - the need for translating that word and the best way of managing that. Does anybody have any thoughts on this?

[jean-gui]

For further clarification, there is no need to create the id on the heading - just the anchor link itself for any heading with an ID?

Yes.

It would be more robust if the anchor markup was handled on the server side rather than with client side JavaScript. It means the functionality will always be there, even if the JavaScript should fail for some reason. I also worry a little about the front end performance, if there is a long page with a lot of headings requiring the creation and insertion of an anchor.

The problem doing it server-side is that we don't always have full control over the data. For example I don't know if we could automatically add the necessary markup in Craft. Asking editors to add the markup is not going to work.

The current manual implementation could be improved for accessibility. The anchor link does not have an accessible name - the symbol is announced as "Section symbol" in Safari with VoiceOver. I recommend that the symbol is contained within <span aria-hidden="true"></span> to stop it being announced by screen readers, and another <span class="visuallyhidden"></span> is added inside the anchor to hold the accessible name of the anchor link. This can be as simple as the word "anchor".

What current manual implementation? My initial message didn't mention that, but part of the issue is to come up with some markup and style for self links. What @koalie did on https://www.w3.org/ecosystems/publishing/#groups is only a temporary measure until we have something "official" in the design system.

This does also raise the subject of internationalisation - the need for translating that word and the best way of managing that. Does anybody have any thoughts on this?

Good point. We could add those self links only for full sites (en, ja, zh-ans) as others languages will have less use for them since we won't have such long pages.