Docusaurus v3 markdown links don't resolve correctly from index pages during build step when trailingSlash is set to false

[maxweisel]

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 all,

(My original issue was closed because my repro didn't match /exactly/. This one matches /exactly/.)

I've got a fresh docusaurus v3 project with trailingSlash set to false in the config, and I noticed that when it resolves relative links from markdown files, it does it incorrectly if the file is a readme.md file within a folder (acting as an index).

In short if you have the following docs folder structure:

docs/test/readme.md
docs/cool-page.md

and test/readme.md contains the following markdown:

[Cool page](../cool-page.md)

running build will generate the following error:

  Exhaustive list of all broken links found:
  - Broken link on source page path = test:
     -> linking to ../cool-page (resolved as: /cool-page)

Despite the error saying it was resolved as /cool-page it is in fact not.

Interestingly, if I switch the link to ./cool-page (removing the ../). It works correctly. My guess is that rather than using the path of the readme.md file when resolving a relative path, it's using the location of the folder that contains it (in this case it assumes the links are coming from a file at the path ./test instead of a file at ./test/readme.md.

Max

Reproducible demo

https://codesandbox.io/p/devbox/runtime-pine-84xm8d

Steps to reproduce

run npm run build on the playground

Expected behavior

It builds correctly without errors

Actual behavior

Exhaustive list of all broken links found:

• Broken link on source page path = test:
  -> linking to ../cool-page (resolved as: /cool-page)

Your environment

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

Self-service

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

[slorber]

Despite the error saying it was resolved as /cool-page it is in fact not.

There is nothing at /cool-page. For your link to work, it must be resolved as /docs/cool-page.

And trailingSlash has an impact on relative link resolution.

---

I'm sorry but your sandbox does not match your text description, which makes things confusing. Please try again by having the text and the sandbox being in sync.

For example your sandbox is using a relative path link (which we don't recommend because it's sensitive to trailingSlash setting changes)

[Cool page](../test2/cool-page)

While your text is using a relative reference to a markdown file

[Cool page](../cool-page.md) 

Those 2 are not the same at all, and will not resolve the same.

---

Most likely it's a mistake on your side, so I'm closing as can't repro. The behavior you see in your sandbox is the expected behavior.

[maxweisel]

The bug works the same regardless of the location of the page being linked. However, I've updated my repro to match the bug /exactly/.

[slorber]

I'm not sure if you expect me to do something, your sandbox now includes many other broken links due to removing other md files.

[Cool page](../cool-page)

[Cool page](../cool-page.md)

The 1st doesn't work, and it's expected because ../cool-page resolved from /docs/test resolves as /cool-page, a path that does not exist

The 2nd work because it's resolved as /test/cool-page, that exists.

I maintain that all this works as intended. If you still believe otherwise please create a minimal repro showing a single broken link being reported and explain why you think the error is a false positive.

Also make sure to properly understand how relative links work on the web (this is not a Docusaurus feature, it is how regular html pages and browsers work, we use the same resolution algo).

Also make sure to read that doc:

[maxweisel]

Just saw the note about adding .md extensions. I'll use that. Thank you

[maxweisel]

I'm still seeing this bug if an image links to a markdown file. This fails claiming the link is broken: [![Cool Page](https://docusaurus.io/img/docusaurus.svg)](../cool-page.md):

  Exhaustive list of all broken links found:
  - Broken link on source page path = /docs/test:
     -> linking to ../cool-page.md (resolved as: /cool-page.md)

As soon as I switch it to a text link, it works despite having the same link path.

I've updated the repro project here: https://codesandbox.io/p/devbox/runtime-pine-84xm8d

[slorber]

Can confirm the bug, related to resolving relative file paths when using an image.

Can reproduce this on our own website:

[text](./installation.mdx)

[![alt](/img/slash-introducing.svg)](./installation.mdx)

Only the first link resolves.

Definitively a bug. Track #9048 for the root cause and the solution. We can keep this issue closed.