search

11ty / 11ty-website

Documentation site for the Eleventy static site generator.
https://www.11ty.dev/
MIT License
479 stars 681 forks source link

Inaccessible heading anchors #222

Closed oliverjam closed 1 year ago

oliverjam commented 5 years ago

(Apologies if this is the wrong repo for this!)

Summary

There are a couple of a11y issues with the heading anchors that appear on hover:

  1. They are not keyboard-focusable unless you hover the heading first
  2. They have no accessible label and are read out as simply "number" ("#")

I saw that Zach got aria-hidden removed from the links generated by markdown-it-anchor (in this issue), but that doesn't seem to have helped.

[Disclaimer: I have only tested in Chrome with Voiceover on macOS]

Not focusable

I cannot tab to the link without hovering the heading first, which means they're inaccessible via keyboard. I think this is caused by the visibility: none.

recording of me unable to tab to focus a heading anchor until I hovered my mouse over the heading

If the anchor should always be accessible, then we should visually hide it with CSS and reveal on hover of the heading and focus of the anchor.

No accessible name

The anchors are not labelled, so even if a Voiceover user managed to focus them they would hear "link, number (#)", followed by "direct link to this heading" (the title attribute). We probably shouldn't rely on title, since it appears JAWS and NVDA don't read it out. I think either an aria-label or a visually-hidden span inside the anchor would be better.

recording of voicover's output when a heading anchor is focused

It's also not clear which heading this is a direct link for, since every anchor has the same title. I'm not really sure what the best practice is here. Should the link be usable on its own (doubling up the heading content for the anchor label) or is it ok to only make sense in context of the heading (requires the user to have heard the heading before tabbing to the link)?

I imagine the former might be annoyingly verbose, but the latter could be confusing. There's a whole discussion of this in this AnchorJS issue. They ended up just labeling every anchor with "anchor", which seems redundant.

For now the quickest win is probably duplicating the title content in aria-label too. I've opened an issue about controlling arbitrary anchor attributes in markdown-it-anchor.

Ryuno-Ki commented 5 years ago

Since I'm about to add it to my blog, too, I'd volunteer to prepare a PR for this (can only test it with Orca on Linux or ChromeVox or Accessibility tab in DevTools).

@oliverjam Could you take a second look at it then? I could look after render it as HTML somewhere online.

zachleat commented 1 year ago

This was fixed in a markdown plugin upgrade! https://github.com/11ty/11ty-website/blob/b76a17461de2d08fa43b37fb6d7d0b8b3c81c979/config/markdownPlugin.js#L36