HTML links broken in markdown when they include URL fragment #

[BTOdell]

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 embedding a HTML a tag links in markdown and the path includes a URL fragment (anchor), then the production build fails saying that the link is broken.

For some reason, there is no error when in hot reload mode (npm start); although hot reload mode might just be designed to ignore these kinds of errors?

Markdown file:

<a target="_blank" href="/page.html#anchor">My Link</a>

Static HTML page:

This is the static HTML content page.<br />
A bunch of space.<br />
A bunch of space.<br />
A bunch of space.<br />
...
A bunch of space.<br />
A bunch of space.<br />

<h1 id="anchor">Anchor</h1>

More content down here.<br />
...
More content down here.<br />

The static HTML page contains an anchor named "anchor" which I should be able to link to from the markdown.

If I remove the anchor from the link:

<a target="_blank" href="/page.html">My Link</a>

Then, there is no broken link. Even though the build is correctly resolving to /page.html in both cases.

Reproducible demo

https://stackblitz.com/edit/github-jgvs2v?devtoolsheight=33&file=docs/broken.md

Steps to reproduce

1. Start with fresh installation of beta16.
2. Edit files as described (also see playground link).
3. Run production build npm run build
4. See error with broken link

Expected behavior

No broken link. Static page exists with correct anchor.

Actual behavior

The production build fails with broken links.

[ERROR] Unable to build website for locale en.
[ERROR] Error: Docusaurus found broken links!

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

Exhaustive list of all broken links found:

- On source page path = /docs/broken:
   -> linking to /page.html#anchor (resolved as: /page.html)

Your environment

• Public source code: https://stackblitz.com/edit/github-jgvs2v?devtoolsheight=33&file=docs/broken.md
• Docusaurus version used: 2.0.0-beta16
• Environment name and version: Node.js 16.14 LTS, Chrome 98
• Operating system and version: Ubuntu 18.04 LTS and Windows 10

Self-service

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

[Josh-Cena]

Thanks for reporting! FYI, you don't need to use the <a> tag because <a> tags are handled exactly the same as []() links. Instead, you can use the pathname: protocol:

[My Link](pathname:///page.html)

Which treats this link as external and therefore doesn't do broken link check.

[BTOdell]

The pathname: protocol just solves everything, doesn't it? 😄

Is this still a bug then? Even though there is a "workaround" by using pathname:, it still sounds like a bug in the broken link resolver. Maybe it's not parsing URLs fully? Or it doesn't think that it needs to because it should only encounter internal documents?

[Josh-Cena]

It is a bug. I've just sent a PR to fix it.

[Josh-Cena]

Fixed in #6812! Thanks for reporting

[monica-m-ps]

Hello @Josh-Cena. This referencing using pathname:/// works... But it always opens in a new tab... Is there a way to open in the same tab? I have 100s of links and don't want to send the user to new tabs everytime... Previous versions I used:

some text... [error message](/payments/api#section/Introduction/Errors) with [HTTP status code]

This worked like a charm before Docusaurus 3.0.0 but now I get an error for brokenlinks... It works locally though...

These are my API docs (Redocly) sitting in a different folder.

[monica-m-ps]

• Scenario 1

some text... [error message](/payments/api#section/Introduction/Errors)

throws an error

- Broken anchor on source page path = /payments/snippets/_handle-errors:
   -> linking to /payments/api#section/Introduction/Errors

But works locally... Worked before Docusaurus 3.0.0.

• Scenario 2

some text... [error message](pathname:///payments/api#section/Introduction/Errors)

This works but opens in a new tab (which we don't want)

[slorber]

@monica-m-ps for the broken anchors in 3.1 that's a new feature, and this is because the Redocly plugin (redocusaurus?) does not use the new API to report existing heading ids it creates.

See https://docusaurus.io/blog/releases/3.1#broken-anchors-checker

Let's track this in rohit-gohri/redocusaurus#321

Until then you can disable with onBrokenAnchors: "ignore". This is a new feature so it only reverts to the previous behavior of not reporting broken anchors at all.

---

For the opening in new tabs, please open a dedicated issue and create a runnable repro using docusaurus.new