broken anchor false positive?

[alewolf]

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

With the new version 3.1 I get broken anchor errors, although the links work just fine. I don't see any issue in the anchor link.

Example: On the page https://sweetcode.com/blog/are-all-payment-gateways-created-equal/ I have one link linking to the pricing section with an anchor that looks like this /plugins/pmw/#pricing-section (it also throws and error when I remove the trailing slash like this: /plugins/pmw#pricing-section

The full link with the anchor looks like this: https://sweetcode.com/plugins/pmw/#pricing-section

You'll find the link in the document by searching for Pro version of the Pixel Manager.

Here's the error output:

Broken anchor on source page path = /blog/are-all-payment-gateways-created-equal:
     -> linking to /plugins/pmw#pricing-section

Reproducible demo

No response

Steps to reproduce

https://sweetcode.com/blog/are-all-payment-gateways-created-equal/

Expected behavior

No broken anchor error thrown on this link: https://sweetcode.com/plugins/pmw/#pricing-section

Actual behavior

A broken anchor error is thrown.

Broken anchor on source page path = /blog/are-all-payment-gateways-created-equal:
     -> linking to /plugins/pmw#pricing-section

Your environment

• Public source code: na
• Public site URL: https://sweetcode.com/blog/are-all-payment-gateways-created-equal/
• Docusaurus version used: 3.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node version 21.1.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): MacOS

Self-service

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

[slorber]

This is working as intended, cf release blog post: https://docusaurus.io/blog/releases/3.1#broken-anchors-checker

You are creating your own anchors, and fall under this case where you need to tell Docusaurus about the anchors:

Use the broken links API:

useBrokenLinks().collectAnchor("pricing-section")

---

Alternatively, you can also add onBrokenAnchors: "ignore" to your config: this will not warn you about such false positives.

---

Note that I'm not sure having multiple h1 elements on a page like you did is a good semantic html practice.

[alewolf]

So that means anchor errors get reported on <h1> but not on <h2> (etc) links?

[slorber]

No, you have to use the API for any anchor you create in your code (if you want to link to it at least, and avoid the warning (that you can turn off anyway)).

What I'm saying is unrelated: it's probably not a best practice to use multiple h1 on the same page. This is unrelated to Docusaurus.

[alewolf]

Ok. I got it mostly working with useBrokenLinks().collectAnchor("pricing-section")

However, there are side cases that I'd like to report. I'm not sure how you want to handle them.

If I add UTM parameters, I get a broken link warning for:

/blog/post#anchor?utm_source=source

I don't get a broken link warning for

/blog/post?utm_source=source#anchor

Both links work. However, the correct way to format such a link is to add the query parameters first and the anchor at the end like this: /blog/post?utm_source=source#anchor

Maybe the warning could explain in more detail what's wrong.

The other case is if I use an anchor link in a markdown file that points to the same document like this: [information](#anchor)

This also throws a warning.

However, if I add the full path, it's fine: [information](/path/to/document#anchor)

If the path ever changes to the document, that's not ideal. I think [information](#anchor) should not throw a warning.

[Josh-Cena]

/blog/post#anchor?utm_source=source

This is simply not a valid query parameter and Docusaurus can't know better than the URL parser itself. I presume it works because of how analytics tools work: they just do a string search for the utm_source fragment (at least that's how the ancient Urchin Tracking Module worked, if I recall correctly).

[information](#anchor)

Really? That should not be an error. It's used extensively on our own website too. If it still happens on the latest version, maybe send another issue with a minimal repro.

[alewolf]

Ok about the anchor. It's not only analytics. Docusaurus opens the correct anchor when a misconfigured URL is clicked. So it's just weird that it throws the broken link error. I know that /blog/post#anchor?utm_source=source is invalid. In my case, I received some texts from a content writer who didn't know about it, and I didn't check. So that's how they ended up in there. I just think it would be nice if other Docusaurus users, who don't know that adding query parameters after an anchor is not a valid way to format a URL, would somehow learn about it. The current warning will leave them more puzzled than help. But if it is not possible to parse this in a way that helps to throw a more informative warning, then that's how it is.

Never mind about [information](#anchor) it was a spelling error.

Thanks!

[slorber]

@alewolf please create repros using Docusaurus.new for each indépendant case, first to prove the issue actually exist and then so that we can study your setup in depth. Here you don't even post the error messages you get.

It's not the role of Docusaurus to teach you about urls. You could also put the domain name after the anchor if you want to. Technically that is probably a valid anchor, so do we want to prevent users from doing so if it's valid bug weird?

Using a ? after a # is weird but if browsers support it, we can't warn users that it is a possible mistake because some users might do that on purpose

[alewolf]

It's not the role of Docusaurus to teach you about URLs.

You don't have to teach me. Luckily I know how a "valid" URL format looks like.

However, Docusaurus flags those wrongly formatted URLs as broken links, even though you admit, in reality those links work. It's not the best user experience for Docusaurus users who don't know why those broken links are flagged as broken, especially when they work.

So here's a CodeSandbox example: https://codesandbox.io/p/live/3be4c123-896c-4acb-bd98-70a669f0737c

[slorber]

Those are actually not wrongly formatted urls.

This url is weird perfectly valid: https://docusaurus.io/docs#anchor?alsoPartOfAnchor=42

It's just that by interverting url parts you probably end up with a valid anchor that is not the one you wanted in the first place.

Docuaurus will tell you that #anchor?alsoPartOfAnchor=42 anchor does not exist on the target page, which is... true

And that anchor is weird, but perfectly valid: we can't reject it because some users migth want to do these weird things that the web allow, on purpose.

[robodl]

I'm experiencing something similar when updating to 3.1 using trailingSlash: true.

Basically all our table of content links report broken anchor

- Broken anchor on source page path = /docs/edit/:
   -> linking to #overview (resolved as: /docs/edit/#overview)

I suspect it has something to do with the trailing slash followed by an anchor tag 🤔 ?

[slorber]

@robodl your issue looks more related to this one: #9880

I can't help without seeing a repro, but maybe you swizzled the Heading component?

[robodl]

@slorber

I haven't swizzled any components.. But I have forked the remark-toc plugin in order to fix an issue with TOC not properly generating when importing other mdx files with headers of their own.

I've come to the conclusion to wait for 3.2 which is supposed to add some support for this case (#3915 (comment)) and see if the anchor links warnings dissapears.

Thanks for the response 👍

[polly-bold]

I am having the same issue. Upon building the site, I get a huge number of broken anchor false positives. We haven't done anything out of the ordinary. Unfortunately, upgrading to docusaurus 3.2 didn't work, either. Did you find anything that resolved this for you @alewolf ?

[slorber]

@polly-bold there are many reasons why it could happen.

Not having a repro, or at least one very concrete example (ie sharing the error message + prod URL + md/link source code) makes it impossible to help you, unfortunately.

What you encounter might be different from what others encounter, so it's important to share as many details as possible.

Can you recreate such false positive case in a sandbox? (https://docusaurus.new/stackblitz). If not, why are you so sure these are legit false positives?

Note your site https://developer.boldcommerce.com/ is publicly accessible so you could use a target URL/heading and a link as a concrete example too, but I need to see the error message for it and the source code of the markdown link being reported as broken.

[lsarni]

@polly-bold for us updating these packages to the versions used in the sandbox fixed it (not sure which one specifically, but when we only updated @docusaurus... it wasn't working)

"@docusaurus/core": "^3.2.0",
"@docusaurus/preset-classic": "^3.2.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^2.0.0",
"prism-react-renderer": "^2.3.0",

We had to change the way we use the prism themes on docusaurus.config.js but it's minimal, and you can see how the new version works on the sandbox.

[erenkan]

Another use case that causes this issue occurs when you use <!-- truncate --> before the titles. On the main blog page, the anchors cannot find the related links, which results in an error. @slorber

- [Section One](#section-one)
- [Section Two](#section-two)

<!-- truncate -->

## Section One

Content for section one.

## Section Two

Content for section two.

[slorber]

@erenkan see #10287