Relative markdown links contain file extensions

[serpro69]

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

I'm following the 5-minute tutorial and discovered that relative file paths are not converted to links (the file extension is not removed from the link, and hence results in 404)

Reproducible demo

https://codesandbox.io/p/sandbox/winter-pine-527qpc

Steps to reproduce

• create docs/foo.md and docs/bar.md files
• Link to bar.md from foo.md:

Link to [bar](./bar.md)

• Open foo page and click on the link

Expected behavior

bar page should open at .../docs/bar

Actual behavior

the url contains file extension, i.e. .../docs/bar.md

Your environment

• Public source code: n/a (I've just initialized a new project with docusaurus and following the tutorial)
• Public site URL: n/a
• Docusaurus version used: 3.2.2
• Environment name and version (e.g. Chrome 89, Node.js 16.4): node v18.16.1
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Ubuntu 22.04

Self-service

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

[slorber]

Yes, that is surprising.

Have you only tried this in codesandbox? Can you try on your computer on a new Docusaurus repo instead?

Because this is a very basic Docusaurus feature that should normally work otherwise we'd get thousands of bug reports.

It seems to run fine locally, or inside StackBlitz: https://stackblitz.com/edit/github-mpurku?file=docs%2Fintro.md

So I suspect this bug is only related to CodeSandbox. Maybe it's a new bug due to recent changes they made, and will self-resolve? 🤷‍♂️

[serpro69]

Hi @slorber ,

I've tried it locally originally on a new docusaurus repo, and it didn't work for me. And then I tried in CodeSandbox when I was filling out this issue.

[slorber]

@serpro69 can you provide a GitHub repo reproduction?

I have one that shows it working as expected:

```md
Let's see how to [Create a page](./create-a-page.md).
```

**Result:** Let's see how to [Create a page](./create-a-page.md).

https://github.com/slorber/docusaurus-starter/edit/main/docs/tutorial-basics/markdown-features.mdx

https://tutorial.docusaurus.io/docs/tutorial-basics/markdown-features#links

[serpro69]

Yes, was just making it :)

Here's the repo - https://github.com/serpro69/docusaurus-10152

For this example I ran npx create-docusaurus@latest docusaurus-10152 classic, then added two pages in the docs dir, one of them containing a link to another page.

Then started docusaurus with npm run start, which results in the same incorrect behavior.

[serpro69]

OK, a bit more debugging and it seems the problem is with start command. When I try to first build and then serve, it works as expected.
Is this expected behavior with the start command then? Or is it broken for that particular use-case?

[slorber]

It's not expected that the start command behave differently. Can you share a non-Codesandbox repro (ideally GitHub) where I can see the problem in action with the start command?

[serpro69]

It's not expected that the start command behave differently. Can you share a non-Codesandbox repro (ideally GitHub) where I can see the problem in action with the start command?

Yes, already did above ;)

Here's the repo - https://github.com/serpro69/docusaurus-10152

[slorber]

@serpro69 when running your GitHub repro, I can see that it works as expected, both start and build commands.

https://pr.new/github.com/serpro69/docusaurus-10152

The UI works, the links are resolved correctly

And there's no markdown link resolution error in the console:

[serpro69]

Hmm, I've just cloned my repo and it also works fine for me on a fresh clone.

I then tried to re-initialize via npx create-docusaurus from scratch and it doesn't work:

I wonder if it's an issue that could be related to npx create-docusaurus command then.

---

UPD: I tried to remove node_modules dir, then run npm ci and then npm run start and that solved the issue.
I think some broken/incorrect dependency is introduced via npx maybe? Which is resolved if you remove all pulled dependencies and re-install them.

Anyways, it looks like this does in fact work as expected, so long as you clean up node_modules after running the initial npx create-docusaurus command

[slorber]

hmmm, weird, I don't know what's happening here 😅

Let's consider it works for now

[slorber]

Problem identified.

This is a legit problem that only happens in dev when you create one file and immediately link to it. Our mdx loader resolves links thanks to a sourceToPermalink mapping, but the way our system is architected will not support "hot reload" for this mapping, it's impossible to resolve links to any newly created files without restarting your dev server.

I'll fix this as part of #10168 (edit: nop I'll open another PR to make things more explicit)