Markdown links point to root-level file when Markdown file with same filename exists

[josh-wong]

Have you read the Contributing Guidelines on issues?

• [x] I have read the Contributing Guidelines on issues.

Prerequisites

• [x] I'm using the latest version of Docusaurus.
• [x] I have tried the npm run clear or yarn clear command.
• [x] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [x] I have tried creating a repro with https://new.docusaurus.io.
• [x] I have read the console error message carefully (if applicable).

Description

When linking to a file within the documentation, the link sometimes resolves to an unintended file in the root docs directory rather than the expected file in the current or relative directory.

For example, suppose a page contains a link like [See this](index.mdx), and the current directory also contains a file named index.mdx. If a root-level docs/index.mdx also exists, the link will incorrectly point to the root file instead of the intended one in the current directory.

This behavior is not limited to index.mdx; it occurs with other filenames as well. It seems that the link resolution logic prioritizes the root docs directory over the relative path, which leads to incorrect navigation and potential confusion for users.

Workaround

If you start a link with ./ ([See this](./index.mdx)), then the issue doesn't occur. However, I don't think this is a solution because, as far as I know, using ./ isn't necessary when pointing to pages in the current directory.

Reproducible demo

https://clinquant-beijinho-49680d.netlify.app/docs/latest/scalardb-cluster/getting-started-with-scalardb-cluster

Steps to reproduce

1. In the docs directory, create a file named index.mdx and add some basic text for testing to the file.
2. In the docs directory, create a subdirectory named test.
3. In the test subdirectory, create a file named index.mdx and add some text that is different from the text in the docs/index.mdx file that you created in step 1.
4. In the test subdirectory, create a file named docusaurus.mdx and add the link [index](index.mdx) to the file.
5. Build the site by running npm run build.
6. Serve the site by running npm run serve.
7. Go to the test/docusaurus page in your browser.
8. Click the index link on that page. You will be taken to docs/index.mdx, which shows the basic text that you added in step 1.

Expected behavior

I was expecting to be routed to the page with the same filename in the subdirectory that I was in.

Actual behavior

I was routed to the root-level (docs) page with the same filename as that in the subdirectory that I was in.

Your environment

• Public source code: See the first sentence (Line 10) in https://github.com/scalar-labs/docs-scalardb/blob/9b00d32b5d862d44aca5aff99c790a118a0d1122/docs/scalardb-cluster/getting-started-with-scalardb-cluster.mdx?plain=1#L10
• Public site URL: See the first sentence after the Heading 1 in the following development environment: https://clinquant-beijinho-49680d.netlify.app/docs/latest/scalardb-cluster/getting-started-with-scalardb-cluster
• Docusaurus version used: 3.7.0
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Brave v1.75.181, Node.js v21.7.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS 15.4

Self-service

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

[sa-abdullah]

Kindly assign this to me

[mtayyabrawan]

Hey @josh-wong I have followed the steps you provide to reproduce this issue but it is working correctly when i clicked [index](index.mdx) it opened docs/test/index.mdx not docs/index.mdx

Docusaurus : v3.8.1 React : v19.0.0 Node : v24.6.0 npm : v11.5.2 OS : Win 10 Pro's WSL2 (Ubuntu 24.04.3 LTS) Chrome : 139.0.7258.157

[slorber]

I can reproduce the problem with the steps above and confirm something weird is happening here.

Runnable repro: https://stackblitz.com/edit/github-vmkujfpc?file=docs%2Ftest%2Fdocusaurus.mdx

All those links target different URLs, while the absence of ./ should still resolve in priority to resolving relative to the current file dir.