I'm building a documentation website using Docusaurus and facing an issue with markdown links specifically when using .mdx
files for inter-page linking. Surprisingly, the markdown content itself renders correctly within .mdx
files, but the links within those files fail to work as expected.
Strangely, the markdown links function perfectly fine when using regular .md
files. However, when I switch to .mdx
files, the links no longer work despite ensuring proper configuration updates.
I have attempted various approaches for markdown links, including URL paths and file paths. Furthermore, I have updated the Docusaurus configuration to include .mdx
files (what is most likely obsolete).
During the build process, I receive the following error message related to broken links:
#0 43.80 [ERROR] Unable to build website for locale en.
#0 43.80 [ERROR] Error: Docusaurus found broken links!
#0 43.80
#0 43.80 Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
#0 43.80 Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.
#0 43.80
#0 43.80 Exhaustive list of all broken links found:
#0 43.80
#0 43.80 - On source page path = /en/docs/advanced/getting_started_robot_framework:
#0 43.80 -> linking to ../intermediate/01_create_project.mdx (resolved as: /en/docs/intermediate/01_create_project.mdx)
I find it puzzling that the official documentation refers to using .mdx files, implying that they should support markdown links. However, despite extensive efforts, I have been unable to resolve this issue.
If anyone has encountered a similar problem or has suggestions on how to enable markdown links within .mdx
files for inter-page linking, I would be immensely grateful for your guidance. Thank you in advance for any insights or recommendations!
I had the same issue. I dropped the .mdx
suffix in the link and it worked. See if it works for you if you link to ../intermediate/01_create_project
instead of to ../intermediate/01_create_project.mdx
.