Broken relative links in docs and i18n translation

[trofim24]

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

Problem with relative links in docs and i18n translation.

Reproducible demo

https://trofim24.github.io/

Steps to reproduce

1. Create a new Docusaurus site with npx create-docusaurus@latest my-website classic -t command from instruction
2. Go to created folder cd my-website
3. Copy only one Markdown file and images use mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/tutorial-extras/img cp -r docs/tutorial-extras/img/** i18n/fr/docusaurus-plugin-content-docs/current/tutorial-extras/img cp -r docs/tutorial-extras/translate-your-site.md i18n/fr/docusaurus-plugin-content-docs/current/tutorial-extras command from instruction
4. Change docusaurus.config.js. Add 'fr' language to locales from instruction and add a navbar item of type localeDropdown from instruction: locales: ['en', 'fr'] and { type: 'localeDropdown', position: 'left', },
5. Run build use npm run build command from instruction

Also you can visit my build site to check broken link: /fr/docs/tutorial-basics/congratulations broken link

Expected behavior

The build is OK

Actual behavior

[WARNING] Docusaurus found broken links!

Please check the pages of your site in the list below, 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:

• Broken link on source page path = /fr/docs/tutorial-basics/congratulations: -> linking to ../tutorial-extras/translate-your-site.md (resolved as: /fr/docs/tutorial-extras/translate-your-site.md)

Your environment

• Public source code: https://github.com/trofim24/my-website
• Public source code of build: https://github.com/trofim24/trofim24.github.io
• Public site URL: https://trofim24.github.io/
• Docusaurus version used: 3.7.0
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 133.0.6943.54 (Official Build) (x86_64), Node.js v20.18.2
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): MacOS Ventura Version 13.7.2 (22H313)

Self-service

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

[slorber]

Yes, I think this is because you only copied one Markdown file.

https://github.com/trofim24/my-website/blob/master/i18n/fr/docusaurus-plugin-content-docs/current/tutorial-extras/translate-your-site.md

It looks like our resolveMarkdownLinks remark plugin, responsible for resolving .md Markdown links to an absolute path, is not powerful enough. It isn't currently able to resolve relative links if the translated docs set is incomplete since we'll have to resolve relative links found in a file against multiple source dirs instead of just one.

Probably a bug involving this function: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-utils/src/markdownLinks.ts I suspect the sourceToPermalink map does not contain all the necessarily information to support this use-case.

---

This is likely a bug we need to investigate, not so easy to resolve. In the meantime I'd suggest that you translate the whole docs at once instead of partially. If you want to translate it partially, it would work better with absolute paths like [translate your site](/docs/tutorial-extras/translate-your-site)

[eduveks]

This limitation is very annoying.

I've been facing this for months, but only noticed recently.

Because not all links are broken, some work and others do not. In some cases, even in EN, some links do not work, but after a page refresh, they works well. I suspect it is something with or without the slash at the end of the URL, but I can't find the behaviour pattern, because in development always works very well, but the behaviour is not the same as when compiled and published, where the crazy broken links happen.

After replacing the relative links with absolute paths, using the /docs/... as the prefix, it finally seems to work fine. @slorber, many thanks.

My problem now is to fix all the links; in my case, there are many MDs...

Here is a simple example of what I've made to work:

https://github.com/netuno-org/doc/commit/2acfb67413c4f0f74568af6c99174be13fde561d

Notice the links changed in EN, and then in the PT translation.

Now online works the same as in development.