If a footnote link works with ordinary browser navigation but fails when your smooth-scroll script runs, check how the script resolves the fragment. A valid HTML ID is not automatically a valid unescaped CSS selector.
Why some footnotes fail and others work
Gutenberg's footnote fix in pull request 82398 prefixes newly generated identifiers with fn-. Older footnotes retain their identifiers. The issue concerns IDs beginning with a digit and scripts that concatenate them into a selector. This means a new article passing a test does not prove that historical footnotes are fixed.
Do not bulk-rename all IDs to make them look consistent. Incoming links and saved references may depend on the original fragments, and each footnote also has a path back to its reference.
Reproduce without changing content
Choose one old article with a failing footnote and one newly created test article. Record the reference link's href and the target element's exact ID. Open each fragment directly in the browser. Then enable the site's normal smooth-scroll behavior and repeat.
- Watch for a selector syntax error in the console when clicking.
- Check whether the target exists exactly once in the document.
- Confirm that the link points within the current page rather than another URL.
- Test the return link from the note to the reference.
- Repeat with keyboard activation, not only pointer clicks.
Old ID: Numeric-leading identifier. New ID: Prefixed identifier. Fallback: Normal navigation stays usable. Motion: Respect reduced-motion preference. Explanatory checklist, not a customer test result.
Fix identifier lookup, not the article archive
When the code already has an exact element ID, document.getElementById(id) avoids interpreting that string as a CSS selector. When a selector really is needed, use correct escaping, such as CSS.escape(id), within a supported browser environment. Resolve and validate the URL before handling it as a same-document fragment. Do not decode arbitrary fragments repeatedly or intercept external links.
For example, the following illustrates the lookup distinction, not a complete scrolling plugin:
const id = '1-example-note';
const target = document.getElementById(id);
// If constructing a CSS selector instead:
const sameTarget = document.querySelector('#' + CSS.escape(id));
Keep native link behavior as the fallback when no target exists. Avoid calling preventDefault before deciding whether the script can handle the link. A smoother animation is not worth turning a usable reference into a dead control.
What a passing regression test includes
| Case |
Expected observation |
| Existing numeric-leading ID |
Correct target without selector error |
| New prefixed ID |
Correct target and return link |
| Missing target |
No JavaScript crash that breaks other links |
| External article link |
Normal navigation remains available |
| Reduced-motion preference |
No forced unnecessary animation |
Also check fixed headers: a correct target can be hidden behind a sticky toolbar. That is an offset or scroll-margin problem, not evidence that the ID lookup failed.
When the entire page URL is missing rather than its fragment, use our permalink and migration 404 guide. For a script-level repair, bring the failing article to HandL WP with the fragment and console error.
Source: Gutenberg footnote identifier fix. The example is explanatory and has not been installed on your website.
References reviewed October 17, 2026. Examples are explanatory, not customer test results.