docusaurus

Have you read the Contributing Guidelines on issues? [x] I have read the Contributing Guidelines on issues. Prerequisites [x] I'm using the latest version of Docusaurus. [x] I have tried the or command. [x] I have tried and re-installing packages. [x] I have tried creating a repro with https://new.docusaurus.io. [x] I have read the console error message carefully (if applicable). Description I believe Docusaurus is a single page app (SPA). When internal links are invoked, the history API is used to update the browser's URL bar. This unfortunately doesn't come with out-of-the-box accessibility support https://www.matuzo.at/blog/2023/single-page-applications-criticism/. The new Navigation API _should_ be better but not ready for prime time yet 🤞🏻 As a result, here's NVDA invoking the "Community" link in the top nav. I'm tabbing to the link, then press Enter to invoke. NVDA announces nothing. https://github.com/user-attachments/assets/16960c37-aaac-49b4-89b9-323071c3ffde macOS VoiceOver is a little inconsistent. I'm again tabbing to the link. First I'm using Enter to invoke. VoiceOver consistently announces nothing. But VO+Space is another common way to invoke links/buttons. VoiceOver sometimes announces the document title in that case, it seems inconsistent. https://github.com/user-attachments/assets/6819e9a8-7346-4ac3-b271-8a3e16a8c0d4 FWIW there's a bit of debate as to whether this is is a WCAG 4.1.3 Status Messages failure (does it fit the definition of a status message?). Reproducible demo https://docusaurus.io/ Steps to reproduce 1. With NVDA (and Chrome in my testing), visit docusaurus.io 2. Tab to a link in the top navigation 3. Press Enter Expected behavior There's a bit of debate on this (see linked blog posts), but I'd argue that since this is basically a MPA (multi page app) navigation, the MPA UX should be mimicked. In a standard MPA nav, NVDA will announce when the page is fully loaded. Note that slower network connections should be considered — the user needs to be aware when the page is fully rendered and ready for interaction. It'd also be nice if they were informed while loading was still taking place. I know the History API doesn't give many options for this, IIRC the Navigation API has the necessary hooks. Actual behavior NVDA announces nothing. Your environment N/A Self-service [ ] I'd be willing to fix this bug myself.

Summary Fixes #11332: SPA route navigations are not announced by screen readers (NVDA, VoiceOver). Root cause Docusaurus already moves focus to the skip-to-content container on route change (PUSH), but that container has a static of "Skip to main content". When a screen reader user navigates, focus lands on that container and the SR announces "Skip to main content region" (or nothing), not the title of the page they landed on. The user knows a navigation happened but not which page they are on. Change Pass the page title down from the to the component, and use it to set the skip-to-content container's to the formatted page title when navigating. The container is focused on route change, so the screen reader announces the page title. The container's is restored to "Skip to main content" on the next render, so the skip link keeps working as before for keyboard users who tab to it. This uses the page title from the prop (formatted via ) rather than reading , because Helmet updates asynchronously (deferred via ), so it is not reliable at the moment focus moves. Why focus management (not a live region) A live region would announce on the audio channel but does not reliably reach refreshable braille displays, and it competes with the new page's own announcements. Moving focus to a meaningful landmark is the one mechanism all screen readers and braille displays agree on, and it matches the MPA behavior the issue asks for. Tests Added verifying that: Focus moves to the skip-to-content container on route change. The container's is updated to the page title when navigating. 116 tests pass in . 51 tests pass in . Typecheck passes for both packages.