Skip to content

fix(a11y): use an attribute selector for the ?id focus target - #2866

Open
0z5a wants to merge 1 commit into
docsifyjs:developfrom
0z5a:focus-anchor-id-leading-digit
Open

0z5a wants to merge 1 commit into
docsifyjs:developfrom
0z5a:focus-anchor-id-leading-digit

Conversation

@0z5a

@0z5a 0z5a commented Nov 19, 2026

Copy link
Copy Markdown

Summary

#focusContent() looks up the ?id= target with dom.find(`#${query.id}`). When the id starts with a digit (?id=2-usage, ?id=2024) that isn't a valid CSS selector, so querySelector throws. On a link to another page, or when the page is opened with that URL, this happens inside the fetch callback before done(), so doneEach doesn't run for that page and plugins like zoom-image, external-script and search (search: 'auto') skip it.

This changes the lookup to [id="${query.id}"], the same form onNavigate() already uses for its heading lookup and the one #2021 used in scroll.js for #2019. #2021 and #2253 (which added #focusContent()) both first shipped in 5.0.0, so the #2019 case has thrown again since then, just from a different line.

It doesn't change slugs. ## 2. Usage still gets _2-usage (#1516), so a GitHub-style #2-usage link still doesn't scroll to that heading; it just no longer throws. An element whose id really starts with a digit, like <h2 id="2024">, now gets focus like any other target.

How I found it

Reading how ?id= targets are looked up, I noticed #focusContent() uses #${query.id} while onNavigate() and scroll.js use [id=…], then confirmed in Chromium that a fresh load of #/guide?id=26 throws on 5.1.0 and doneEach doesn't run. A live case is the Tainacan wiki (5.1.0): the link from https://wiki.tainacan.org/#/indexing-pdf to ./settings-page.md#1-search-and-performance logs '#1-search-and-performance' is not a valid selector and the images on the settings page don't get zoom-image. Details are in the issue.

Where this can show up in practice

Numbered headings with a hand-written table of contents ([1. Overview](#1-overview)) are a common pattern in docs that are also read on GitHub, and pure-number anchors come from things like comment widgets (#2019). On those pages any doneEach plugin is skipped after following such a link. Besides the Tainacan wiki I haven't seen a field report.

Related issue, if any:

Fixes #2865

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

Testing

  • Two e2e tests in test/e2e/anchor-scroll.test.js:
    • a link to guide.md#2-usage: on develop the page error is the SyntaxError and doneEach only ran for #/; with the change there are no page errors and doneEach ran for #/ and #/guide?id=2-usage.
    • [Jump to 2024](#2024) next to <h2 id="2024">: on develop the heading never gets focus; with the change it does.
  • Both fail on develop and pass with the change in Chromium, Firefox and WebKit (Playwright), and the two tests with --repeat-each=20 pass 120/120 across the three engines. The existing anchor-scroll tests (?id=target-section) pass before and after.
  • npm run lint, npm run test:unit (54), npm run test:integration (79) and npx playwright test --project=chromium (107) pass.
  • In Chromium 156 with zoom-image, a fresh load of the issue's #/guide?id=26: 5.1.0 dist/ logs the SyntaxError, doneEach doesn't run and the image isn't zoomable; with the built dist/ from this branch there is no error, doneEach runs, <p id="26"> has focus and the image is zoomable. Control: #/guide without ?id on 5.1.0 runs doneEach and the image is zoomable.
  • Not run: Edge, and real Firefox/Safari outside Playwright.

Platform: macOS

Tested in the following browsers:

  • Chrome (Chromium 156, and Playwright Chromium)
  • Firefox (Playwright Firefox 151 only)
  • Safari (Playwright WebKit 26.5 only)
  • Edge

#focusContent() looked up the target with `#${query.id}`, which is not a
valid selector when the id starts with a digit. querySelector threw, and
on a fresh load or a link to another page the throw skipped doneEach.
Use [id="..."] like onNavigate() already does.
@vercel

vercel Bot commented Nov 19, 2026

Copy link
Copy Markdown

@0z5a is attempting to deploy a commit to the Docsify Team on Vercel.

A member of the Team first needs to authorize it.

@vercel

vercel Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
docsify-preview Ready Ready Preview Nov 19, 2026 9:31am UTC

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the numeric-ID focus lookup fix.

No open issues 🎉

What changed in this PR

Fixes Docsify’s focus lookup for ?id= targets that begin with a digit, addressing #2865 without changing heading slug generation.

Changes:

  • Uses an attribute selector to prevent numeric-leading IDs from causing selector errors and interrupting navigation hooks.
  • Adds end-to-end regression tests for navigation completion and focus on a numeric ID.
File Description
test/​e2e/​anchor-scroll.test.js Adds coverage for doneEach completion, absence of page errors, and numeric-ID focus.
src/​core/​event/​index.js Changes the focus-target lookup from an ID selector to an attribute selector.

Review effort: Balanced

This branch was successfully deployed

1 active deployment
Preview — 4ec66189 Deployed Nov 19, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

?id= that starts with a digit still throws in 5.x (#2019 again, now from #focusContent())

2 participants