Docusaurus: Link Component with or without useBaseUrl

[jbolda]

🐛 Bug Report

When using the useBaseUrl hook, the base url is composed dependent on if current page was navigated to through "spa navigation" or visiting the url directly. If one navigates to a url with the "spa" mode, the trailing slash appears to be missing. If you refresh the page, the trailing slash is added. The trailing slash appears to break all of the relative links then.

This could possibly be a misunderstanding with the docs and we are not supposed to be using the hook, but the docs for Link and useBaseUrl do not make it clear when you should use useBaseUrl.

Have you read the Contributing Guidelines on issues?

Yes.

To Reproduce

(gif alt: shows steps as noted above)

Expected behavior

Internal routing to work.

Actual Behavior

It seems to work inconsistently depending on how you have arrived on the page.

Your Environment

• Docusaurus version used: 2.0.0-alpha.55

Reproducible Demo

• Permalink to live url: https://deploy-preview-49--tauri.netlify.app/
• Permalink to code at above url: https://github.com/tauri-apps/tauri-docs/tree/ba99d196f5022807922b3efd0b4330c6e37e4c46

[Laegel]

https://v2.docusaurus.io/docs/docusaurus-core/#usebaseurl
They say

We highly recommend you to use this.

So I guess whenever you use Link, you should use useBaseUrl.
Our main problem doesn't come from those Link components but from MD links in the docs.
So I've been replacing relative links with absolute links (you can try to reproduce in the live URL).

[yangshun]

It seems to work inconsistently depending on how you have arrived on the page.

Yes but it's also because of browser behavior. If you use a relative href, the final result depends on whether your current page has a trailing slash at the back.

When using relative links:

• URL: example.com/intro, href: help -> result: example.com/help
• URL: example.com/intro/, href: help -> result: example.com/intro/help

When using absolute links:

• URL: example.com/intro, href: /help -> result: example.com/help
• URL: example.com/intro/, href: /help -> result: example.com/help

So either you use a trailing slash for all your internal links, or use absolute links.

[jknoxville]

So either you use a trailing slash for all your internal links, or use absolute links.

As a user, always using a trailing slash doesn't currently seem to be an option. The navbar sidebar sends you to pages without trailing slashes. Then refreshing that page adds a trailing slash.

As far as I can tell, this means all relative URLs are broken depending on how you use the website. IMO we should issue a fix for this soon or make it clearer that they don't work, maybe by throwing an error at build time or something like that.

The docs are still implying relative URLs should be ok: https://v2.docusaurus.io/docs/markdown-features#referencing-other-documents

Also, even when specifying a relative url in a markdown file, the resultant a-tag on the page has an absolute href, so I don't think the browser's behaviour is the problem here, the wrong absolute path seems to be being produced by docusaurus itself.

[yangshun]

The navbar sidebar sends you to pages without trailing slashes. Then refreshing that page adds a trailing slash.

Hmm good point I think we should fix the sidebar in this case.

[jknoxville]

I started working on adjusting the sidebar to always make sure internal to links have trailing slashes, and I'm happy to continue that, but it feels like slapping a bandaid on the symptoms instead of addressing the root cause.

For the docusaurus website itself, the navbar config currently contains no trailing slashes, so we'd need to make the same change in the navbar so people don't accidentally link to the non-trailing slash version of pages. For the same reason, it probably makes sense to do the same thing in the Link component too.

That is all fine, but if anyone ever links to any docusaurus page without a trailing slash there'll be a strange half broken experience. Even though it is the linker at fault, the docusaurus site is the one that will appear broken.

Looks to me the relative to absolute translation is done by react-router-dom. It might be worth doing the opposite of this to redirect any non-trailing urls to trailing ones: https://jasonwatmore.com/post/2020/03/23/react-router-remove-trailing-slash-from-urls

@yangshun what's your reaction to adding a redirect rule? I've never used react-router before but it seems possible. If I understand right, this would mean we'd never have to worry about trailing slashes in links, there would just always be one.

[yangshun]

I think Docusaurus should take a stance on this and introduce trailing slashes to all Docusaurus-generated links while we're still in alpha. Some users Markdown links might break now but at least it's consistently breaking in both development and production, unlike now when it's breaking only in production and sometimes depending on hosting provider.