Scrolling behavior for pages with anchor tags is broken across Chrome, FF, Safari

[priyatam]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

• I'm using the latest version of Docusaurus.
• I have tried the npm run clear or yarn clear command.
• I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• I have tried creating a repro with https://new.docusaurus.io.
• I have read the console error message carefully (if applicable).

Description

I've been using Docusaurus for a large project / corp for 8+ months. However our MDX content has increased 5x since initial POC. Recently, we noticed this core bug: Anchor tags from within a page are currently inaccessible when a user types the url directly on browser. The anchor links work when user clicks through the TOC, and if you refresh the page after clicking anchor link from TOC—but not when user accesses the link directly on a new browser session (link sharing is thus broken)

I've looked at previous issues but our chrome browser is not enabled for "experimental features". This issue occurs across Chrome / FF / Safari (last 3 latest versions) with Chrome's inspector set to defaults. See sample reproducible code below.

Sharing precise documentation links is a fundamental P0 feature (works in plain html without additional js scroll effects). Without this feature consistent across browsers, users can't share links, hence documentation site is unusable.

Reproducible demo

No response

Steps to reproduce

1. Add several anchor links on a page (to force scroll)
2. Copy the link - /docs/page#anchor-link
3. Paste it on a new window/tab on browser (simulating a user has a shared this link to someone and they're accessing it directly via browser address bar)

Expected behavior

Regardless of anchor link, page always loads and stops at top level and doesn't scroll to anchor link.

Actual behavior

page should scroll to anchor link

Your environment

• Public source code: https://stackblitz.com/edit/github-ttyuxa?file=docs%2Fintro.md
• Public site URL: https://github-ttyuxa-vee6tx51--3000.local-credentialless.webcontainer.io/docs/intro#start-your-site-4
• Docusaurus version used: 2.0.0-rc.1 (issue persists on 2.2.0)
• Environment name and version (e.g. Chrome 89, Node.js 16.5.0):
• Operating system and version (e.g. Mac OSX Monterey 12.6.1 ):

Self-service

• I'd be willing to fix this bug myself.

[slorber]

Hey

It works on Docusaurus and other sites:

https://docusaurus.io/docs#design-principles

If it's broken on your specific site, I can't help if you don't give me the real production link + the source code to inspect it.

Using StackBlitz is not a so reliably way to test this because it is running in dev mode, for which the behavior may be different.

If you run StackBlitz in prod mode, it works as expected:

So, I'm closing until a production repro is provided, because 2.2 seems to work fine in prod mode.

[priyatam]

Seems inappropriate to close an issue when I took the time to share a Stackblitz repo to "reproduce the bug" with exact steps and all info asked in the issue template.

I would appreciate if you can reopen this issue to discuss troubleshooting steps to identify potential browser issues, mdx formatting issues, version issues, js isses (to name a few) to help Docusaurus early 2.x adopters currently in production with 1000+ documents.

@Josh-Cena Please advise.

[Josh-Cena]

I would also appreciate a production link, thanks—development mode and production mode have a world of differences.

[priyatam]

I'm afraid I can't share a production link as it's an internal site for developers. Do you have a recommendation to troubleshoot browser issues?

[priyatam]

Does Docusaurus document this anywhere on the website - "development mode and production mode have a world of differences"?

[Josh-Cena]

Yes: https://docusaurus.io/docs/cli#docusaurus-start-sitedir

Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.

Does your issue actually reproduce in your internal production deployment? Are you deploying the output of docusaurus build?

[Josh-Cena]

(Also, I'd love to reopen the issue and help you walk through debugging, but my write access isn't renewed yet, so we'll need to communicate like this. Please also understand that if anchor links actually don't work, we'll get much more furious issues than this single one, so it's likely a deployment issue)

[priyatam]

Yes, using Docusaurus since early 2.x beta and it's deployed in prod mode with more than 30+ ejected theme components and UX overrides, custom sidebars.js and clientside Search -- working in prod. I recently found the issue with anchor links which was occurring intermittently on a few docs, but now across all documents making it a Sev1 issue.

You might be right that this is a deployment issue. What can I inspect in output folder?

[Josh-Cena]

If there are many ejected theme components, this is very likely a theme conflict (e.g. race conditions). Docusaurus implements the scroll behavior with client code, so if your code also tries to respond to location changes, the two scroll events may cancel each other. This certainly requires vetting the entire custom theme implementation, which I understand can be tedious, but there isn't any way to make it easier (a normal day in front end development). Maintainers' time is also limited (myself's especially—I have much schoolwork to catch up), so unless there's a narrowed-down culprit in our codebase, I'm reluctant to call it a Docusaurus bug, since it doesn't manifest on our own website.

What can I inspect in output folder?

You can run yarn build and inspect the build folder.

[priyatam]

Got it, appreciate your pointers to troubleshoot, Josh. I quickly scanned our ejected components from theme-classic - most of the changes are in css, some jsx wrappers with div tags - I didn't see any js event overrides. Could you point me to teh code for "Docusaurus scroll behavior with client code"?

CodeBlock
DocItem
DocPage
DocSidebar
DocSidebarItem
DocSidebaritems
Footer
Icon
NavBar
Toc
TocItems

[Josh-Cena]

Hmmm, frankly this is a hard issue to debug. If the changes are all CSS and markup, I have very little idea, sorry. FYI, this is our implementation:

docusaurus/packages/docusaurus/src/client/ClientLifecyclesDispatcher.tsx

Lines 30 to 39 in ca3dba5

	function scrollAfterNavigation(location: Location) {
	const {hash} = location;
	if (!hash) {
	window.scrollTo(0, 0);
	} else {
	const id = decodeURIComponent(hash.substring(1));
	const element = document.getElementById(id);
	element?.scrollIntoView();
	}
	}

[Josh-Cena]

I took another look—the code I gave above is only used for in-site navigation. I believe the first anchor link navigation is using the browser's default behavior, but I'm not too sure either at this point.

[priyatam]

Also, to step back — I'm able to reproduce the bug in a fresh Stackblitz repo, here's the url (I had tp update since stackb;itcz throws off links after some time) on all three browsers.

This may have nothing to do with theme overrides.

[Josh-Cena]

Thanksgiving starts tomorrow, I'll try to take a look since I have more time to spare than usual. Nevertheless, you can confirm these links all work, right?

• https://jestjs.io/docs/jest-platform#jest-get-type
• https://docusaurus.io/docs/configuration#custom-configurations
• https://typescript-eslint.io/rules/consistent-type-assertions#assertionstyle

[priyatam]

Yes, the three links work.

[slorber]

@priyatam the StackBlitz url you share is a local URL. It only works for you because of how StackBlitz works. You can just share the Stackblitz code link instead of the preview because only the code link will work.

---

I'll reopen this issue if I see a Docusaurus 2.2 / canary site in production mode with the problem visible, and code I can inspect, without any swizzled component.

If you have swizzled a lot of components, it's likely that some components diverged too much from the official theme code, and you have to maintain those components. My suggestion is to delete all these components and see if it works better. If it doesn't, then try to do "dichotomy debugging" and reintroduce half the swizzled components to finally see which components are causing troubles.

If the problem only appears with your swizzled components, then it's not a Docusaurus bug, but a bug in your own site instead.

I only have 3d/week on Docusaurus and can't provide support for such issues when I don't have a clear repro. Having the issue being kept open wouldn't be more helpful because it's not actionable from my side, or too time-consuming to figure out what can go wrong with your site. If you want the problem to be solved, we are happy to help, but we kindly ask you to invest your own time to create a good repro, instead of us investing our time to try to guess what the problem could be.

The ideal repro for me is a GitHub repo, init Docusaurus site commit + your changes in a 2nd commit that leads to the reported problem. This way I can save time and understand immediately what could be wrong after your modifications. A Stackblitz repro is also perfectly fine although it's less convenient to see what you have changed exactly.

As you will likely provide one, we can try to help you even if this issue is closed, and even if we don't consider it a Docusaurus bug.

So, I'm waiting for your fixed StackBlitz repro link, am still willing to help, but will keep the issue closed until it's proven it's a Docusaurus bug.