Skip to content

a11y: Headings are read verbosely by VoiceOver #2980

Open
@qwerzl

Description

@qwerzl

Describe the bug

We should add an aria-label to the headings. Currently with aria-label not specified, VoiceOver returns heading level 1, 2 items What is VitePress, visited, link, Permalink to "What is VitePress?", which is very unclear and verbose.

Reproduction

Just head to https://vitepress.dev/guide/what-is-vitepress on Mac, open VoiceOver and click on any heading.

Expected behavior

An aria-label should be added to heading elements. Take the # What is VitePress? as an example, it should be rendered as:

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

Then VoiceOver returns Heading level 1, What is VitePress?.

System Info

System:
    OS: macOS 14.0
    CPU: (10) arm64 Apple M1 Pro
    Memory: 98.42 MB / 16.00 GB
    Shell: 5.9 - /bin/zsh
  Binaries:
    Node: 19.7.0 - ~/.nvm/versions/node/v19.7.0/bin/node
    Yarn: 1.22.19 - ~/.nvm/versions/node/v19.7.0/bin/yarn
    npm: 9.5.0 - ~/.nvm/versions/node/v19.7.0/bin/npm
    pnpm: 8.6.0 - ~/.nvm/versions/node/v19.7.0/bin/pnpm
  Browsers:
    Chrome: 116.0.5845.187
    Safari: 17.0

Additional context

I am willing to fix this bug by myself. However as I'm not familiar with MarkdownIt, I think I need some help on where to customize the rendering rules of headers.

Validations

Metadata

Metadata

Assignees

No one assigned

    Labels

    a11yRelated to accessibilitystale

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions