Relative links break when imported / transcluded from other markdown files

[jknoxville]

🐛 Bug Report

We can transclude markdown files within others by importing them and using them as JSX.

If the transcluded file contains a relative link, e.g [Link](../target), then depending on which file imports it, it will fail.

Interestingly, importing it works in some files, but not in others, I haven't quite figured out the exact conditions that determine this though, but I have a repro for the failing case.

Have you read the Contributing Guidelines on issues?

Yes

To Reproduce

Checkout jknoxville@e8ad7c1

yarn build inside the website dir.

Expected behavior

I expect the build to succeed, and /docs/api/plugins/ to contain a link to /docs/cli

Actual Behavior

yarn build fails.

Error: Docusaurus found broken links!

Please check the pages of your site in the list bellow, and make sure you don't reference any path that does not exist.
Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken links found:

- On source page path = /docs/api/plugins:
   -> linking to ../../cli (resolved as: /cli)

    at Object.reportMessage (/Users/jknox/github/docusaurus/packages/docusaurus-utils/lib/index.js:440:19)
    at Object.handleBrokenLinks (/Users/jknox/github/docusaurus/packages/docusaurus/lib/server/brokenLinks.js:142:17)
    at async buildLocale (/Users/jknox/github/docusaurus/packages/docusaurus/lib/commands/build.js:150:5)
    at async tryToBuildLocale (/Users/jknox/github/docusaurus/packages/docusaurus/lib/commands/build.js:32:28)
    at async Object.mapAsyncSequencial (/Users/jknox/github/docusaurus/packages/docusaurus-utils/lib/index.js:396:24)
    at async build (/Users/jknox/github/docusaurus/packages/docusaurus/lib/commands/build.js:58:25)

However, when using yarn start and loading localhost:3000/docs/api/plugins/ directly from the URL, the link does work.

Your Environment

• Docusaurus version used: direct for of the main repo
• Operating system and version (desktop or mobile): MacOS

Reproducible Demo

jknoxville@e8ad7c1

[jknoxville]

This is something I might be able to look into myself in the new year. Putting this here to keep track of it, and in case anyone has any pointers where I should start looking.

[slorber]

Thanks for reporting this.

Are you sure this exact error is obtained by running a build on your exact repro code?
I find it surprising but will take a look later.

Relative links are added as-is to the browser, so depending on where your partial is required you might end up with this relative path being resolved differently. It is always resolved against the current URL, we don't do anything about it.

To make things work reliably, you'd better use the relative md file path. It will resolve against the slug of the target document, keeping the version part of the URL (ie the user will stay in the same version when navigating from source to target)

[jknoxville]

Aha! Thanks @slorber using the filename does indeed seem to fix it - I hadn't made the connection that they would be treated differently, and what you say about unchanging links makes sense.

Fwiw, I re-ran the build on that unchanged commit and it does still fail. I'll leave it up to you to decide what to do with this issue, but it's not urgent, especially since using files sounds like a perfectly reasonable alternative.

[slorber]

Let's keep it open for now, will see some day if I see the reason it fails on that repro, but yes, using relative md file paths is the best solution from linking docs between each others across a given version

[slorber]

Going to close this now, because our doc strongly encourage to use absolute links or relative md file paths.

Relative paths are not processed in any way by docusaurus, and it's your responsibility to make sure that the final relative link will work in the final page that includes the partial.

Not 100% related but we added a more consistent support for the _ prefix, mostly for MDX partials: #5173