Header anchors not accessible to screen reader users.

[sabicalija]

Describe the bug

The header anchors are not accessible to screen reader users.

<h1 id="what-is-vitepress" tabindex="-1">
  What is VitePress?
  <a class="header-anchor" href="#what-is-vitepress" aria-hidden="true">#</a>
</h1>

Setting aria-hidden on focusable elements (that are not hidden from all users) fails test "aria-hidden elements do not contain focusable elements".

I'm preparing a PR to fix this issue.

Reproduction

No special configuration necessary. Header anchors are enabled by default.

This issue can be tested on the official VitePress site or any other basic vitepress deployment using the default-theme.

Expected behavior

Provide an accessible default configuration for markdown-it-anchor and update styling of header-anchors accordingly.

A possible solution could look like this:

<div class="header-wrapper">
  <h1 id="what-is-vitepress" tabindex="-1">What is VitePress?</h1>
  <a class="header-anchor" href="#what-is-vitepress" aria-label="Permalink to "What is VitePress?"">#</a>
</div>

A viable markdown-it-anchor configuration could look like this.

{
  anchor: {
    permalink: MdItAnchor.permalink.linkAfterHeader({
      style: "aria-label",
      assistiveText: (title) => `Permalink to "${title}"`,
      visuallyHiddenClass: "visually-hidden",
      wrapper: ['<div class="header-wrapper">', "</div>"],
    }),
  },
}

Additionally, some updates for anchor styling are necessary too.

.vp-doc .header-wrapper {
  position: relative;
}

.vp-doc .header-wrapper .header-anchor {
    line-height: 32px;
    position: absolute;
    top: 0;
}

.vp-doc .header-wrapper h1 + .header-anchor {
    line-height: 40px;
    font-size: 32px;
}

.vp-doc .header-wrapper h2 + .header-anchor {
    padding-top: 25px;
    line-height: 32px;
    font-size: 24px;
}

.vp-doc .header-wrapper h3 + .header-anchor {
    line-height: 28px;
    font-size: 20px;
}

.vp-doc .header-anchor:hover,
.vp-doc .header-anchor:focus,
.vp-doc h1:hover + .header-anchor,
.vp-doc h2:hover + .header-anchor,
.vp-doc h3:hover + .header-anchor,
.vp-doc h4:hover + .header-anchor,
.vp-doc h5:hover + .header-anchor,
.vp-doc h6:hover + .header-anchor {
  opacity: 1;
}

System Info

System:
  OS: Linux 5.15 Ubuntu 20.04.5 LTS (Focal Fossa)
  CPU: (8) x64 Intel(R) Xeon(R) CPU E3-1505M v5 @ 2.80GHz
  Memory: 19.26 GB / 31.13 GB
  Container: Yes
  Shell: 5.0.17 - /bin/bash
Binaries:
  Node: 18.14.0 - ~/.nvm/versions/node/v18.14.0/bin/node
  Yarn: 1.22.19 - ~/.nvm/versions/node/v18.14.0/bin/yarn
  npm: 9.3.1 - ~/.nvm/versions/node/v18.14.0/bin/npm
Browsers:
  Chrome: 110.0.5481.177
  Chromium: 110.0.5481.100
  Firefox: 110.0.1

Additional context

More details about test "aria-hidden elements do not contain focusable elements" can be found at https://dequeuniversity.com/rules/axe/4.4/aria-hidden-focus.

Validations

• Follow our Code of Conduct
• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.