onBrokenAnchors reports named anchor tags as broken links

[jrahal-mx]

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

When you use named anchors (E.g., <a name="anchor">Some Text</a> or self-closing ) in a doc page, onBrokenAnchors reports it as a broken link.

Reproducible demo

No response

Steps to reproduce

1. In docusaurus.config.js, set onBrokenAnchors to Warn (if not using the default setting).
2. Edit a doc page.
3. Add a named anchor anywhere on the page. E.g., <a name="anchor">Some Text</a>
4. Add a link to the named anchor, e.g., [Link Text](#anchor)
5. Save the page.
6. Build the site (yarn build).

Expected behavior

No console feedback. onBrokenAnchors ignores the arbitrary named anchor because it's only supposed to work for anchors declared with the Heading component.

Actual behavior

onBrokenAnchors reports the named anchor as a broken anchor. Example:

[WARNING] Docusaurus found broken anchors!

Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist.
Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken anchors found:
- Broken anchor on source page path = /user-types-and-permissions:
   -> linking to #anchor (resolved as: /user-types-and-permissions#anchor)

Note that on the rendered page, the anchor works.

Your environment

• Public source code:
• Public site URL: (issue encountered locally during build)
• Docusaurus version used: 3.1.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Version 120.0.6099.129 (Official Build) (arm64)
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS Ventura 13.4.1 (22F82)

Self-service

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

[slorber]

We'll try to improve this, but this is currently the intended behavior, because all anchors must be "collected" for the broken link checker to see them.

CF-related issue: #9763 (comment)

The current suggested workaround (requiring v3.1.1) is:

import Link from '@docusaurus/Link';

<Link id="my-anchor"/>

Please note that <a name="xyz"/> is not valid anymore as per HTML5 spec, that's why I choose to not support it in our Link component.
See https://stackoverflow.com/questions/484719/should-i-make-html-anchors-with-name-or-id

---

I'm keeping this open for now, as there's an opportunity for us to improve the DX.

But please share more details about your use case. For now, it's hard to know if you created that JSX inside a React file or an MDX file, and that matters to me to design an improved solution, for which the technical solution could be radically different (remark plugin VS custom JSX pragma).

Reading the repro steps, I kind of understand that the anchor is in an MDX doc file right?
Would you expect this to also work inside a React file such as src/pages/index.js?

[jrahal-mx]

Yes exactly, my immediate use is to be able to have arbitrary (non-heading) anchors in MDX files. I haven't needed to use them in React pages.

I would love for onBrokenAnchors to be able to validate arbitrary anchors, along with heading anchors, in MDX pages. That's the case with the workaround you provided (Thanks!).

If onBrokenAnchors can't validate arbitrary anchors, I'd expect it to ignore them instead of mistakenly reporting them as broken.

[slorber]

I would love for onBrokenAnchors to be able to validate arbitrary anchors, along with heading anchors, in MDX pages. That's the case with the workaround you provided (Thanks!).

We'll try to add support for <div id="anchor"/>, <a id="anchor"/> etc in Markdown files.

However it's not possible to add support for <MyCustomComponent id="anchor"/> and you'll have to keep using the Docusaurus API in that custom component.

If onBrokenAnchors can't validate arbitrary anchors, I'd expect it to ignore them instead of mistakenly reporting them as broken.

We validate each link anchor against all the anchors we successfully extracted from the target page, so it's important to collect all of them.

For a given page, we either validate or not, but there's no middle ground. What you ask for basically means disabling the broken anchor check

[jrahal-mx]

We'll try to add support for <div id="anchor"/>, <a id="anchor"/> etc in Markdown files.

That would be great!

For a given page, we either validate or not, but there's no middle ground. What you ask for basically means disabling the broken anchor check

I understand. That's not what I want. I would much rather the arbitrary anchors get checked along with the heading anchors. It's just that right now, <a> anchors return false errors because they're not supported, which makes the broken anchors check noisy.

I really appreciate your taking the time to consider this, BTW.

[nijikokun]

Is there some way to suppress this warning, this is currently blocking us from upgrading

[slorber]

@nijikokun a warning does not prevent your site from building, and yes this is configurable as explained in the docs and release notes:
https://docusaurus.io/blog/releases/3.1#broken-anchors-checker

onBrokenAnchors: "ignore"

Disabling it is not a big deal, it just reverts to what we had in v3.0-

But it would be better to fix the broken anchors and help us figure out when we report false positives (if it's a different case from the one above)