Inaccessible markdown heading links

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I’m using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

Heading hash links in Markdown docs are missing the accessible name. Screen reader users who tab through the page by keyboard and focus on the links hear only “Direct link to heading” (the text inside the title attribute of hash links).

Also, when users of screen readers populate a list of links on the page, it is showing the following:

Basically, they do not know where the links will take them since there is no meaningful text content.

Reproducible demo

https://docusaurus.io/docs#fast-track

Steps to reproduce

1. Go to any docusaurus docs page, for example, https://docusaurus.io/docs
2. Turn on the screen reader (e.g. NVDA on Windows, or VoiceOver on Mac)
3. Tab through the heading links:

• Fast Track (the first hash link)
• Docusaurus: Documentation Made Easy (the second hash link)
• and so on

1. When focused on the link, the screen reader announces something like “Direct link to heading, link”

Expected behavior

The hash links should have an accessible name, ideally the heading content, so screen reader users know where the links are pointing to.

The suggestion for the new HTML structure of a sample link:

<h2 id="fast-track">
  <a href="#fast-track" title="Direct link to Fast track">Fast track</a>
</h2>

The implementation of the # character can be still made on hover, similarly as on MDN.

Actual behavior

The hash links have no accessible name (no unique text content) so screen reader users do not know where the links are pointing to.

The current HTML structure of a sample link:

<h2 id="fast-track">
  Fast Track 
  <a class="hash-link" href="#fast-track" title="Direct link to heading">&ZeroWidthSpace;</a>
</h2>

Your environment

• Public site URL: https://docusaurus.io/docs#fast-track
• Docusaurus version used: 2.2.0

Self-service

• I’d be willing to fix this bug myself.

[zmrhaljiri]

Thanks a lot, much appreciated! If aria-label will be there, no need for me to swizzle then 😃 💚

[slorber]

Thanks for the explanations!

Another approach can be the aria-label way you suggested, which would also work since the accessible name of the link would not be empty space or “#” character, but “Direct link to Fast track”:

I guess we can move on and just add this new aria-label then, that looks like a good enough solution

Sorry, I missed your points about the other solutions before

Not saying those linked examples are good accessibility examples, just wanted to illustrate other docs sites preferring not having clickable anchor headings.

Thank you for taking the time looking to this, really. I realize it can be quite tricky and complex. I am currently building a site dedicated to web accessibility using Docusaurus, and I’d greatly appreciate if accessibility issues and difficulties can be handled

We also appreciate having a base of users caring about accessibility, as this helps up improve on topics we may not have expertise on 😄

optionally have control over the markup so I can adjust it.

In any case, you should be able to swizzle headings components and implement your own markup, but we should have good accessibility by default.

If aria-label is not good enough for you, you can swizzle and make it use heading anchor links instead.