Docusaurus URL with # does not always navigate to the correct anchor with external images in it

[furkanarabaci]

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

Hello! My name is Furkan from Appcircle CI/CD. Thanks for creating such a convenient tool that powers our documentation. We also open sourced our own documentation as well.

I've come across some slightly minor problem when there's an image on a documentation link, anchoring and referencing them is slightly off sometimes, especially when there are too many close anchors to each other, it gets noticeable pretty fast.

It happens on our documentation, https://docs.appcircle.io but I've also checked the https://docusaurus.io itself to check it happens and I noticed that it happens on a few pages with images on it. Docusaurus.io doesn't have that many images so it's harder to catch the issue there. I've added that in reproducible demo stage on a page I've found which has an image in it.

The context is, when there are lots of images and anchor link is on bottom of the images, it renders afterwards.

I've also checked the function that is responsible for scrolling with anchor, but I've found nothing wrong with it on sight.

Thank you for your consideration! Sorry that I won't be able to fix the issue myself.

Reproducible demo

StackBlitz Demo:
https://stackblitz.com/~/github.com/furkanarabaci/docusaurus-anchor-issue

From Official Appcircle Documentation:

1. Navigate here: https://docs.appcircle.io/updates/release-notes#-fixed-1
2. Find the last item on the list that starts with:

The case that selection of the adhoc auto device register

3. click the auto device register link
   Observe the scroll behavior

Steps to reproduce

1. Create a page with images in it and an anchor (h2 or lower) below the images
2. Locally navigate to that page using e.g. /docs/start#anchor (make sure it's uncached)
3. Notice that the anchor is not properly aligned

Case 2: - Reload Deemed as invalid ✅
1. Go to a link with anchor in it
2. Scroll a bit down or up, doesn't matter
3. Reload or force reload the page,
4. Notice the scroll state sometimes aligns with anchor, but most of the time it doesn't

Expected behavior

The page to be scrolled properly to its anchor

Actual behavior

Notice that the anchor is not properly aligned on both cases. Case 1 is a guess game, most of the time it works but there are cases which it doesn't work

Your environment

• Public source code: https://github.com/appcircleio/appcircle-docusaurus
• Public site URL: https://appcircle.io
• Docusaurus version used: 2.1.0 - 2.4.0 and 3.0.0 -> Persists on all
• Environment name and version (e.g. Chrome 89, Node.js 16.4): NodeJS 16, 18. Edge version 119.0.2151.46, Safari version 17.1, Google Chrome 107.0.5304.63
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): MacOS, Windows

Self-service

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

[slorber]

Thanks

A few examples: docs.appcircle.io/distribute/apple-devices#automatically-adding-registered-devices-to-the-provisioning-profile docs.appcircle.io/distribute/create-or-select-a-distribution-profile#delete-a-distribution-profile

I can't reproduce any issue on those links.

Can you record a video and specify which browser you are using?

Can you provide a minimal open source repro using docusaurus.new?

---

Reproducible demo

docusaurus.io/docs/advanced/routing#generating-and-accessing-routes

That's a different bug, Mermaid diagrams are not rendered at build time but only on the client-side. This produces annoying layout shifts. This bug is tracked in #8299

There are two cases: Case 1: - Navigation

1. Go to a link with anchor in it (make sure it's uncached)
2. Notice that the anchor is not properly aligned

Case 2: - Reload

1. Go to a link with anchor in it
2. Scroll a bit down or up, doesn't matter
3. Reload or force reload the page,
4. Notice the scroll state sometimes aligns with anchor, but most of the time it doesn't

Please report the different cases independently and provide a link/repro so that we can investigate each case in isolation.

For each case please share at least a link, md source, screenshot or video

Note if you scroll then reload, the std browser behavior is not to scroll back to the url anchor but rather to restore the former scroll position.

[furkanarabaci]

@slorber Thank you for your reply. In that case, case 2 is already invalid. I didn't provide a reproducible demo because our documentation is open to the public and the code is open source. But I understand, for the sake of simplicity I'm going to create a new one and try the case there

[furkanarabaci]

@slorber Sorry for the late reply.
Upon further investigation, I was able to pinpoint the issue. The problem happens on our website (presumably on Docusaurus as well) if there's a local link with anchor e.g.

[Local Navigation](/seo#structured-content)

And since it is loaded right away, assumably due to image content it doesn't scroll properly to the anchor. I'll also try it on docusaurus.new for the sake of simplicity.

Also, should I edit the title&description to match the issue, because the correct issue is a bit more specific than I've provided.

[furkanarabaci]

@slorber I've edited the issue with reproducible docusaurus.new demo, please take a look

[Josh-Cena]

Hi! This is working as intended. We match the default browser behavior of eagerly scrolling, and it will be very tricky to wait for images loading, because our default optimizations make images not load at all unless they scroll into view! If you want to avoid layout shifts caused by image loading, remember to add explicit width and height attributes that match your image's dimensions. This is the default behavior if you use the Markdown ![]() syntax; see #6339

[furkanarabaci]

Hi! This is working as intended. We match the default browser behavior of eagerly scrolling, and it will be very tricky to wait for images loading, because our default optimizations make images not load at all unless they scroll into view! If you want to avoid layout shifts caused by image loading, remember to add explicit width and height attributes that match your image's dimensions. This is the default behavior if you use the Markdown ![]() syntax; see #6339

I see, then it's better to determine width/height standard and style it with fixed dimensions will solve the problem at hand. Thank you!