Broken link in a-tag not detected about docusaurus

[slorber]

np. StackBlitz works fine for me on Chrome, and CodeSandbox has been a bit of a pain lately.

I thought those links where reported in docusaurus v2, but guess I confused something then in my testing.

Docusaurus v2 used MDX v1, and <a> tags in MDX (not JSX) used to be mapped to <Link>, so yes Docusaurus v2 was able to report such issues. That behavior might have been convenient for your particular use-case, but also lead to unexpected behaviors for other users, and MDX decided to do a breaking change and keep the primitive JSX tags found in MDX docs unchanged (unless you process them explicitly with a remark plugin).

The reason why we use the a tag is for example that it is nested in a complicated table. But with docusaurus v3 we could get rid of some things 🤔

You can also use the MDX provider and put our link component in scope:
https://docusaurus.io/docs/markdown-features/react#mdx-component-scope

Then you can use <Link> anywhere instead of <a>. Also what prevents you from using a Markdown link in the table instead of JSX?

Wdym with that? Because the above link is broken, no? And aren't all relative links to a path with a .md extension broken and only possible in Markdown directly?

It is broken in your particular setup, but technically it might not be.

You added this page to https://tutorial.docusaurus.io/docs/intro, and the link targets ./tutorial-basics/create-a-page.md.

So, web browsers will resolve this relative link to https://tutorial.docusaurus.io/docs/tutorial-basics/create-a-page.md

This link is not a Docusaurus SPA route, but it might still exist in practice:

• Run echo "I exist" >> static/docs/tutorial-basics/create-a-page.md
• Run echo "I exist" >> build/docs/tutorial-basics/create-a-page.md
• Reverse proxy /docs/tutorial-basics/create-a-page.md to an existing path/file

Docusaurus has no way to check your deployment process does not involve creating files that Docusaurus is not aware of.

Keep in mind people use Docusauurs in fancy ways. They might generate Javadoc on the same domain and link to it from their Docusaurus site. They might want users to download or browse markdown files source code instead of navigating to the Docusaurus page created from this very markdown file.

---

Perhaps we can enhance the eslint plugin to encourage the user using <Link> or regular markdown link []() instead of <a>

Not sure but afaik ESLint only lints ES files, not MDX.

Or a remark plugin that would do something similar as the broken link ? Check for <a> tags and warn the user about this

Yes, that's a possibility, but it should rather not be too aggressive. I'm afraid this warning could be annoying for most users.

Maybe we could limit it to only local relative paths, and only if the href is hardcoded to a location that ends with .md or .mdx?

[OzakIOne]

I created a repro and I don't have any issue https://stackblitz.com/edit/github-893vqu?file=docs%2Fintro.md

[slorber]

Add a broken link somewhere in an a-tag. I added Broken Link. in the intro.md file. Which doesn't work because of the extension. But any broken link should work.

By design, we do not check for <a href=""> links in either JSX or MDX. These links might as well target:

• a remote url
• a local html page in your /static folder
• a local html page that you copy in your build folder after the build
• a local html page that is served through reverse proxy config

If we reported these links as broken, other users would complain that our broken link checker reports false positives, and will ask us for a way to opt-out. Instead we let you opt-in to the broken link checker, only if you use our <Link> component.

The Docusaurus broken link checker only verifies links created through the <Link> component, ensuring you do not target routes that do not exist in the Docusaurus SPA. In MDX files, Markdown links are verified, but <a> tags are not Docusaurus/SPA <Link> but rather regular html <a> tags so they are not verified.

This behavior is a deliberate choice of Docusaurus, and this works as it is intended.

Note that since MDX v2+, a tag such as <a> will be left as-is and not mapped to the <Link> Docusaurus component. This means that a Markdown link will use <Link> (SPA soft navigation) while a <a> tag will use regular web navigation. This is not our decision and is a documented MDX v2 breaking change, although it makes sense to us, and you can restore former behavior with a remark plugin if needed.

Note: using Gitpod for repros is not ideal, and I had to signup for a service I don't need just to be able to see your repro's code.

[slorber]

What we might investigate is more a feature request than a bug.

How can we prevent/discourage the usage of JSX anchor tags when it makes more sense to use a Markdown link?

<a href='./tutorial-basics/create-a-page.md'>Broken Link</a>.

should rather be rewritten as:

[Broken Link](./tutorial-basics/create-a-page.md)

Maybe we could warn users when they write the former?
(or even be more opinionated and do the transformation ourselves?)

However something important to keep in mind: even if the former is very likely to be a mistake, it remains valid to create a regular relative link to a path with a .md extension. So if we warn, we must provide a way to disable the warning.

[OzakIOne]

Perhaps we can enhance the eslint plugin to encourage the user using <Link> or regular markdown link []() instead of <a>

Or a remark plugin that would do something similar as the broken link ? Check for <a> tags and warn the user about this

[Dr-Electron]

Thanks for your answer. I thought those links where reported in docusaurus v2, but guess I confused something then in my testing. Sorry for bothering than.

And sorry for using, but the other sandbox tools just crash all the time for me 😅 . So I thought as this repo uses Gitpod too, you might have an account. Will do a public repo next time 👍

[Dr-Electron]

The reason why we use the a tag is for example that it is nested in a complicated table. But with docusaurus v3 we could get rid of some things 🤔

But now I'm curious about something else.

However something important to keep in mind: even if the former is very likely to be a mistake, it remains valid to create a regular relative link to a path with a .md extension. So if we warn, we must provide a way to disable the warning.

Wdym with that? Because the above link is broken, no? And aren't all relative links to a path with a .md extension broken and only possible in Markdown directly?

I think in general we are aware that we try to use markdown wherever possible. So not sure if a warning would help. But yeah I guess it could still be nice if optional 👍