broken anchor false positive?

[alewolf]

broken anchor false positive?

[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.