facebook / facebook/docusaurus
"deep-linking" to anchor links not always working (proposed solution)
- Dominant language
- TypeScript
- Stars
- 66.2k
- Forks
- 10k
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 52
Description
### Have you read the Contributing Guidelines on issues?
- [x] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#issues).
### Prerequisites
- [x] I'm using the latest version of Docusaurus.
- [x] I have tried the `npm run clear` or `yarn clear` command.
- [x] I have tried `rm -rf node_modules yarn.lock package-lock.json` 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
Here's a proposed fix for: When linking to an anchor-ref in a docusaurus document, an apparent race condition may cause the in-page scroll to fail. This appears to be an old issue (#8351 for example and is an [acknowledged problem in dev](https://github.com/facebook/docusaurus/issues/6392#issuecomment-1015335095) -- also mentioned in [the CLI documentation](https://docusaurus.io/docs/cli#:~:text=Please%20note%20that%20some%20functionality,work%20as%20expected%20in%20production.)). Even though this issue mostly affects dev environments, fixing it would be a boon for developers...and the race condition that causes it can make it a problem with "slow-loading" apps.
The fix is fairly straightforward: here's a [link to my code](https://github.com/arikorn/companion/blob/fix_docusaurus_anchor_linking/docs/src/hash-nav.js)
The same code is copied in the sandbox linked below, as well, but is commented out in the config for the demo (see below). FWIW, the code has been picked apart by code rabbit to cover all sorts of edge cases, see my related [Companion PR](https://github.com/bitfocus/companion/pull/4036) for details and diagnostics (you'll have to expand resolved issues to see descriptions of the edge cases)...
I _think_ the fix would go [here](https://github.com/facebook/docusaurus/blob/f659aefec430be995494d8730cb77b38acda4b2a/packages/docusaurus/src/client/ClientLifecyclesDispatcher.tsx#L55) more permanently if you agree with the need?? I'd be happy to give it a shot with your support.
### Reproducible demo
https://codesandbox.io/p/devbox/silly-andras-68yl3g?file=%2Fdocusaurus.config.js%3A156%2C5-156%2C18
### Steps to reproduce
1. Go to the demo link
2. Try the three different anchor-nav links. Only the second one will take you to the anchor ("Generate a new site"; the other two go to the top of the page)
3. If you uncomment the `clientModules` line near the end of docusaurus.config.js (make sure it recompiles) and try again everything works.
### Expected behavior
all three links should go to "Generate a new site" in the intro page.
### Actual behavior
see above
### Your environment
- Public source code: code sandbox and GitHub linked above
- Public site URL: see above
- Docusaurus version used: "3.9.2"
- Environment name and version (e.g. Chrome 89, Node.js 16.4): latest chrome, sandbox
- Operating system and version (e.g. Ubuntu 20.04.2 LTS): code sandbox
### Self-service
- [x] I'd be willing to fix this bug myself.
Contributor guide
Assessment
This issue has not been assessed yet.