Broken links checker: inconsistent trailing slash behavior

[Jannik]

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

The broken link checker sometimes requires a trailing slash and sometimes it works without it.

The fix is then to do

[reported link]: /docs/test#abc
[working link]: /docs/test/#abc

Reproducible demo

No response

Steps to reproduce

You can reproduce it in our docs repository: https://github.com/21TORR/docs

1. check it out

2. run pnpm install

3. go to this file https://github.com/21TORR/docs/blob/live/docs/php/tooling/janus-php.mdx and change the links:

   - [Composer bin plugin]: /docs/php/tooling/#composer-bin-plugin
   + [Composer bin plugin]: /docs/php/tooling#composer-bin-plugin
   ...
   - [the note about it]: /docs/php/tooling/#phpunit
   + [the note about it]: /docs/php/tooling#phpunit

4. run pnpm build

And you will get the error:

Exhaustive list of all broken anchors found:

• Broken anchor on source page path = /docs/php/tooling/janus-php:
  -> linking to /docs/php/tooling#composer-bin-plugin
  -> linking to /docs/php/tooling#phpunit

Expected behavior

I am not very familiar with the age old issue of trailing slashes and their handling in Docusaurus. But the pages themselves are accessible without trailing slash, so I would assume that the broken link checker would then just normalize the linked page before checking?

Or are there cases where these links will actually 404?

Actual behavior

The links are reported as issues, even if copying the link and pasting it into the browser works flawlessly.

Your environment

• Public source code: https://github.com/21TORR/docs
• Public site URL:
• Docusaurus version used: 3.3.2
• Environment name and version (e.g. Chrome 89, Node.js 16.4): the build is run on Cloudflare Pages with Ubuntu 22.04.2 and Node 18.17.1
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): see above

We have a public repository that I could share, however I fixed all the cases there. I will look at reproducing the issue however.

Self-service

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

[Jannik]

Just added a reproducer

[Sébastien Lorber]

Note: please next time create a smaller sandbox repro. It's much easier than dealing with a large custom site with repro instructions.

---

Agree there is something unexpected here, only happening for broken anchors (not pathnames).

Repro: https://stackblitz.com/edit/github-u4bsfu?file=src%2Fpages%2Findex.js,src%2Fpages%2Findex.module.css

          <Link
            to="/docs/intro/#getting-started"
          >
            {'/docs/intro/#getting-started'}
          </Link>

          <Link
            to="/blog/welcome"
          >
            {'/blog/welcome'}
          </Link>

          <Link
            to="/blog/welcome/"
          >
            {'/blog/welcome/'}
          </Link>

[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 = /:
  -> linking to /docs/intro/#getting-started

If we don't report /blog/welcome/ as broken path, there's no reason to report /blog/welcome/#existingAnchor as a broken anchor.

---

But the pages themselves are accessible without trailing slash

That might be the case on your current host, or when using docusaurus serve, but it doesn't mean it will be the case for every host. To keep your site portable it's better to always link to the canonical URL.

[Jannik]

@slorber thank you for your response.

I tried to repro it in a smaller setup, but wasn't able to.

That might be the case on your current host, or when using docusaurus serve, but it doesn't mean it will be the case for every host. To keep your site portable it's better to always link to the canonical URL.

Yes, the web server might treat these requests differently, depending on the trailing slash. In our case, it's Cloudflare Pages and both seem to work.

Is there some documentation about which URL is the canonical one? With or without trailing slash?

[Sébastien Lorber]

Is there some documentation about which URL is the canonical one? With or without trailing slash?

If you choose trailingSlash: undefined it depends if you put a trailing slash or not in your doc slugs. Otherwise it's the URL with/without the trailing slash according to the setting.

Otherwise your all site pages have this standard meta attribute that crawlers (Google) will use:

<link data-rh="true" rel="canonical" href="https://docusaurus.io/docs/installation">

And here's also some doc on how multiple hosts behave differently regarding trailing slash and static file hosting. As you will see, there's no standard behavior.

https://github.com/slorber/trailing-slash-guide