Heading anchors should include the inert property

[davemackintosh]

Screen readers can't handle the anchors as they are as they retain focus when you go to them, the output html should include the inert property to prevent any interactibility since they're not a visible item in the page but a functional one in the hierarchy.

[kivikakk]

Reopening as we ended up having to revert #574 — it ended up making the anchor unusable (see #574 (comment)).

We're drafted a new way of displaying and formatting the header/anchor combos at GitLab (see gitlab-org/gitlab!183564), using a custom formatter (yay! see gitlab-org/gems/gitlab-glfm-markdown!76). If this proves out well, I think it'd be worth upstreaming into Comrak as the default. tl;dr instead of <h1><a …></a>heading text</h1>, do <h1><a …>heading text</a></h1>, and then style to taste (e.g. adding a 🔗 on hover with ::before or ::after).

For context, the current default — namely, an empty anchor at the start of the heading element — originates as an emulation of what GitHub's own HTML pipeline would once output. You can see approximately what was happening on GitHub at the time around here. iirc I left Comrak's anchor empty because I didn't want to add octicon and similar target-specific attributes, leaving that to the user.

At any rate, this is now not especially helpful, seeing as folks have ended up using it as-is, and it's not screen reader friendly (as documented here!). GitHub also now do something different, so we're not really doing anything useful by partially emulating old behaviour.

[kivikakk]

Marking this as "good first issue"; my suggestion would be to follow the pattern we established in GitLab's custom formatter, as we've extensively tested it for a11y concerns and deployed it with no issues so far.

Here's the relevant code: https://gitlab.com/gitlab-org/ruby/gems/gitlab-glfm-markdown/-/blob/33aa7fa32744e4b5249ed18519a11f3295afa9ea/ext/gitlab_glfm_markdown/src/formatter.rs#L473-512

Note:

• Contrary to my comment above, we're not including the full text within the <a> any more; the substantive change is moving the <a> to the end.
  • Having the header text be a link to itself is confusing behaviour, can be odd with screen readers (defeats the purpose), and fails pretty badly if there are any links within the header itself.
  • Moving the <a> to the end, on the other hand, is a noticeable improvement for screen readers! Before they'd just read out "link to heading" for the empty <a> at the start of the header and then run those words straight into the heading text. Now we get the header text, and then the (now-accessible) link to the heading.
• We include the original text content in data-heading-content on the anchor; this is to allow for localisable rewrites of aria-label when desired.