fix(a11y): preserve sidebar focus after navigation

[puneetdixit200]

Summary

Keeps keyboard focus on the activated sidebar link after Docsify finishes rendering the destination route.

For hash-mode navigation, the router now carries the original link click event through the hashchange callback. The event layer uses that clicked sidebar link to focus the matching link in the freshly rendered sidebar instead of moving focus to the main heading, whose programmatic focus is intentionally visually hidden.

Related issue, if any:

Fixes #2600

What kind of change does this PR introduce?

• Bugfix
• Feature
• Code style update (formatting, renaming)
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

For any code change,

• Related documentation has been updated, if needed
• Related tests have been added or updated, if needed

Does this PR introduce a breaking change?

• Yes
• No

Tested in the following browsers:

• Chrome
• Firefox
• Safari
• Edge

Verification run:

• npm run build
• npx playwright test test/e2e/sidebar.test.js --project=chromium
• npm run test:unit
• npm run lint
• git diff --check

[vercel]

Someone is attempting to deploy a commit to the Docsify Team on Vercel.

A member of the Team first needs to authorize it.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docsify-preview	Ready	Preview	Sep 10, 2026 3:37am UTC

[paulhibbitts]

Thanks very much for this helpful PR @puneetdixit200 !

My knowledge of accessibility is quite basic - I used the following steps to test your PR:

1. Open PR preview
2. Use the TAB key to step through elements of the user interface, stoping on a navigation item in the Sidebar
3. Use the RETURN key to activate selected link and display relevant content
4. Using the TAB key stop on a second navigation item in the Sidebar
5. Use the RETURN key to activate the second selected link and display relevant content

Doing the above I see that the selected Sidebar item keeps focus - please confirm this is a valid test of the changes you submitted. Thanks again, Paul.

[paulhibbitts]

Thanks very much @puneetdixit200 for this PR! Based on my own review this PR looks to address the keyboard navigation issue, and @msftedad has also looked at the same PR build with the same assessment.

[sy-records]

I made some changes:

Restore focus to the activated sidebar link after route rendering.
Track sidebar targets by link type and normalized URL, and ignore clicks
that do not navigate the current browsing context.

Use normalized URL matching to support encoded paths and avoid unsafe CSS
selector interpolation. Preserve the existing mobile behavior of closing
the sidebar and moving focus to the rendered content.

Add regression coverage for hash and history routing, page and section
links, app-name links, cancelled navigation, encoded URLs, and mobile
navigation.

[paulhibbitts]

Thanks for the updated PR @sy-records !

Using the new PR preview build I I did the following:

• Use the TAB key to step through elements of the user interface, stoping on a navigation item in the Sidebar
• Use the RETURN key to activate selected link and display relevant content
• Using the TAB key stop on a second navigation item in the Sidebar
• Use the RETURN key to activate the second selected link and display relevant content

Focus remained on the selected item in the Sidebar during all of the above! Thanks again, Paul.

[trusktr]

Nice simplification and canonicalization with the helpers, and test updates @sy-records. 👍