Broken link check is case-insensitive

[birdofpreyru]

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

Hey. Not sure, is it a bug, or a feature, but currently the broken links check by Docusaurus is case-insensitive. It would be case-sensitive if routes objects used for the match had sensitive: true flags, but currently they don't have this field. The case-sensitivity matters if generated documentation is served from a service, like Google.Cloud Storage, which treats file URLs in case-sensitive manner.

Reproducible demo

No response

Steps to reproduce

N/A

Expected behavior

N/A

Actual behavior

N/A

Your environment

• Public source code:
• Public site URL:
• Docusaurus version used:
• Environment name and version (e.g. Chrome 89, Node.js 16.4):
• Operating system and version (e.g. Ubuntu 20.04.2 LTS):

Self-service

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

[Josh-Cena]

Are you using Mac/Windows? Our route matching algorithm uses the file system API to decide if the respective file exists, and Mac/Windows is case-insensitive. You would get case-sensitive behavior on Linux (which I would assume most deployment systems are). I don't know if we want to add additional complexity of determining whether your file server is case-sensitive because most servers seem to be case-insensitive.

[birdofpreyru]

@Josh-Cena I am using Ubuntu 22.04.2 LTS, and having this issue, so I don't think matchRoutes() from react-router-config relies on the file system API to match; I guess it just directly compares given URL strings, and does not care if corresponding files exist on the disk.

[slorber]

Makes sense to me 👍

We should match sensitively by default, but this might prevent existing sites from building so it's a breaking change.

I will try to do the change for v3 and provide a secret env variable in case it's annoying for some users (also useful until their bad links get fixed).

Eventually, we can add an option to decide how the broken link checker should match, but let's wait first to see if users complain and if this is really needed.

[slorber]

Note to myself

lost 1h investigating this and it's a bit more complicated.

---

filterExistingFileLinks filters the link ahead of the matchRoutes comparison call.

And this function is case-insensitive on case-insensitive filesystems:

async function isExistingFile(filePath: string) {
  try {
    return (await fs.stat(filePath)).isFile();
  } catch {
    return false;
  }
}

---

I'm not sure of the benefits of keeping filterExistingFileLinks anyway, it's kind of a useless double protection for regular SPA routes, so I'm in favor of removing it. But maybe some parts of it should be kept?

Need to study this more in-depth, but now is not the ideal time.

[caramelmelmel]

Hi @slorber will this be continued?

[slorber]

Need to study this more in-depth, but now is not the ideal time.

Until v3 is released this issue is not a short term goal to fix

[slorber]

As part of the v3.1 broken anchor checker:

• feat(core): make broken link checker detect broken anchors - add onBrokenAnchors config #9528
• https://docusaurus.io/blog/releases/3.1#broken-anchors-checker)

We removed the weird filterExistingFileLinks function I mentioned above, because it prevented Docusaurus from detecting actual broken links.

Now the broken link checking is case sensitive, see playground:
https://stackblitz.com/edit/github-efpqba?file=docusaurus.config.ts