markdownmdxdocusaurus

Docusaurus: Markdown links not working with .mdx files for inter-page linking


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!


Solution

  • 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.