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

  • Check if you're on the latest VitePress version.
    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.

Activity

added
a11yRelated to accessibility
and removed on Sep 17, 2023
added a commit that references this issue on Sep 18, 2023
7d47b4c
added a commit that references this issue on Mar 8, 2025
5df3a54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    a11yRelated to accessibilitystale

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Participants

      @brc-dd@qwerzl

      Issue actions

        a11y: Headings are read verbosely by VoiceOver · Issue #2980 · vuejs/vitepress