Docusaurus: [v2] Improve md interlinking doc / experience

[cncolder]

@slorber: it was initially a bug report, what we can improve is here: https://github.com/facebook/docusaurus/issues/2851#issuecomment-642654109

---

🐛 Bug Report

Different behavior between '.mdx' and '.md' extensions in markdown link.

• [Button](./docs/Button.md)
• [Button](./docs/Button.mdx)

Have you read the Contributing Guidelines on issues?

yes

To Reproduce

1. In README.md [Button](./docs/Button.mdx)
2. docusaurus start
3. Click Button link.

Expected behavior

Navigate to docs/button same as [Button](./docs/Button.md)

Actual Behavior

It will open a download dialog in chrome 83.

Your Environment

• Docusaurus version used: 2.0.0-alpha.56
• Environment name and version : Chrome 83, Node.js 14
• Operating system and version : desktop

Reproducible Demo

(Paste the link to an example repo, including a siteConfig.js, and exact instructions to reproduce the issue.)

[lex111]

In README.md Button

We need a repo to reproduce this issue. In our docs we reference the mdx file, and that works fine.

If you have a Button.md file and you refer to it as Button.mdx, then of course linking will not work properly, because it these are different files.

[krillboi]

Getting this as well. Linking like this [**Development**](/docs/development/development-introduction.mdx) and pressing the link downloads the file instead of navigating to it. Right now we link without the .mdx extension but since we're trying out versioning now, not using the extension breaks the links as far as I can read here: https://v2.docusaurus.io/docs/versioning/#linking-files

Might it have something to do with using absolute paths? Or linking to files in a deeper file structure than 1 level?

[krillboi]

Did a quick peek into the source code, and might the follow line be the issue ? https://github.com/facebook/docusaurus/blob/68a1bb1ebf04da1d97cfea0d8c4944771a426fb2/packages/docusaurus-utils/src/index.ts#L63

The regex seems to only account for .md files.

[slorber]

@krillboi it does not seem related to extRE you mentionned

@cncolder the links have to be relative to current docs, they are not resolved against the root of your site. ./ === current doc's folder.

I've tested on D2 website:

[test](markdown-features.mdx)
[test](using-themes.md)

[test2](./markdown-features.mdx)
[test2](./using-themes.md)

[test3](../docs/markdown-features.mdx)
[test3](../docs/using-themes.md)

[test4](/docs/markdown-features.mdx)
[test4](/docs/using-themes.md)

Only the 4th test does not work, for BOTH md and mdx

This is actually expected, we don't support absolute paths. D2 supports versioning so the docs are not always in the ./docs folder.

The problem is not the extension, it's absolute links starting with /docs, or bad relative links.

If you feel there's a difference between md/mdx, please give proper repro steps, ideally a github repo.

[slorber]

I'm renaming this issue, because we need to document this better.

Currently, we just say something here: https://v2.docusaurus.io/docs/next/versioning#linking-files

We should mention to avoid absolute paths, and probably add something to the "markdown feature" doc (as some users won't read the versioning doc).

Also it could be nice to warn/error if the user is using an unexisting relative path or an absolute path with the md/mdx extension

Is someone from MLH interested to work on this?

[krillboi]

@slorber Ah of course, didn't catch that, but that makes a whole lot of sense.

The reason we have been using absolute links is because our folder structure isn't flat and might be several levels deep, so having links like [**Development**](../../../../../../development/development-introduction) isn't exactly ideal, but I get why absolute paths break when versioning is used. Thanks for the clarification.

[cncolder]

This will happened when you add a new .md file then in another .md ad a link to this new .md,

I think this answer for me. I use rsync sync another /docs together into one repo.

tarojsx/ui/README.md -> tarojsx/tarojsx.github.io/docs/ui/README.md
tarojsx/ui/docs -> tarojsx/tarojsx.github.io/docs/ui/docs
tarojsx/hooks/README.md -> tarojsx/tarojsx.github.io/docs/hooks/README.md
...

This keep same folder structure in tarojsx/ui and tarojsx/tarojsx.github.io.
User can navigate between README and docs in github.
Docusaurus can generate website correctly.

[slorber]

@cncolder this is what I understand:

You have a github README with links such as [x] [List](./docs/components/List.mdx) so that users can navigate from the readme.

You copy the readme to ./docs/ui so that the readme is available in the site (https://tarojsx.github.io/docs/ui/README/)

In such case, the relative links do not work anymore, because the paths are broken. You need to replace [x] [List](./docs/components/List.mdx) by [x] [List](../components/List.mdx)

Is that right?

[cncolder]

@slorber yes. But now I have resolve file path. My docs folder like this:

tree tarojsx.github.io/docs

docs
├── hooks
│   ├── README.md
│   └── docs
│       └── useLogger.mdx
└── ui
    ├── README.md
    └── docs
        └── components
            └── List.mdx

https://github.com/tarojsx/tarojsx.github.io/tree/docusaurus/docs

[krillboi]

@slorber
It seems the <Link> component does not work the same as writing a markdown link when using relative paths.

[**Button**](../../../../api/classes/classtouchgfx_1_1_button.mdx)
=>
http://localhost:3000/docs/4.13/api/classes/classtouchgfx_1_1_button

<Link to="../../../../api/classes/classtouchgfx_1_1_button.mdx">Button</Link>
=>
http://localhost:3000/docs/4.13/api/classes/classtouchgfx_1_1_button.mdx

Removing the extension in the <Link> produces the correct link, but I'd like to keep it consistent throughout my files. Is there a reason why https://v2.docusaurus.io/docs/versioning/#linking-files says "Remember to include the .md extension"? Is that important or can I leave it out?

[krillboi]

Also another variance from markdown links to the <Link> component is the following:

[**Button**](api/classes/classtouchgfx_1_1_button.mdx)
=>
http://localhost:3000/docs/4.13/api/classes/classtouchgfx_1_1_button

<Link to="api/classes/classtouchgfx_1_1_button.mdx">Button</Link>
=>
http://localhost:3000/docs/4.13/development/ui-development/ui-components/buttons/api/classes/classtouchgfx_1_1_button.mdx

So it seems the markdown link correctly finds the root, while the <Link> component does not (that path does not exist, the markdown link is correct).

[slorber]

@krillboi when you use <Link/> you provide a path, not a file. Behind, it's just regular ReactRouter Link, there's no additional logic.

This path may be created in various ways, not necessarily related to MD files, including using the pages, the addRoute api: https://v2.docusaurus.io/docs/lifecycle-apis/#actions

We resolve MD doc links to their appropriate versioned paths, as a convenient thing for the user to build versioned docs, but we don't currently do that for link components.

We could make it work, but it's a whole new feature to design and work on

[krillboi]

Alright, I understand :) For now I think I will streamline it by prepending all my absolute links with the current version in a post process of creating a version then.

[krillboi]

Maybe I should add that the reason this is an issue is because you cannot write markdown links inside a react component, so whenever we use a link inside one of our components, we have to use the <Link> component and then lose out of the versioned path as a result.

[slorber]

@krillboi if you linked to an existing MD file, how are we supposed to know which version to link to?

Pages are always global, docs are (can be) versioned. When you are on a page, there's no specific version in the scope. The best we could do is link to the current version of the doc.

[krillboi]

@slorber Sorry I was misunderstanding something, using the relative path without extension inside <Link> makes it work.

Is there any difference in leaving out the extension in a markdown link?

[Button](../../../../api/classes/classtouchgfx_1_1_button)

vs

[Button](../../../../api/classes/classtouchgfx_1_1_button.mdx)

[slorber]

yes, it's documented to put the extension, otherwise it will just be a normal route pathname

https://v2.docusaurus.io/docs/next/versioning#linking-files

[slorber]

Hey,

I think we can close this but tell me if there's something more to discuss