Relative markdown links broken

[emillaine]

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.
• [ ] I have tried the npm run clear or yarn clear command.
• [ ] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
• [ ] I have tried creating a repro with https://new.docusaurus.io.
• [X] I have read the console error message carefully (if applicable).

Description

Both of these work correctly when navigating in the GitHub repo, but break in Docusaurus:

• When trailingSlash: true, a markdown link [`api` file of a library](code_and_name_organization/#libraries) in /docs/design/functions.md incorrectly navigates to /docs/design/functions/code_and_name_organization/#libraries. It should navigate to /docs/design/code_and_name_organization/#libraries.

• When trailingSlash: false, a markdown link [Language specification](lang) in /docs/spec/README.md incorrectly navigates to /docs/lang. It should navigate to /docs/spec/lang.

There are more links that fail in similar ways, these are just examples.

Adjusting these links in the markdown source is not an appropriate solution, since they work correctly in the GitHub interface where the files are being edited, so people will keep adding more similar links.

Reproducible demo

https://github.com/emlai/carbon-lang/tree/website/website

Steps to reproduce

1. Configure trailingSlash as per description.
2. Start dev server.
3. Go to the corresponding page in the docs.
4. Click on the corresponding link.

Expected behavior

Navigates to the correct path (see description).

Actual behavior

Navigates to an incorrect path (see description).

Your environment

• Public source code: https://github.com/emlai/carbon-lang/tree/website/website
• Public site URL: https://emlai.github.io/ (currently deployed with trailingSlash: true)
• Docusaurus version used: 2.0.0-rc.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 103.0.5060.134, Node v16.16.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS Monterey 12.4

Self-service

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

[Josh-Cena]

Is it your goal to make relative links like code_and_name_organization/#libraries work? We do state in our documentation that relative links like these are unstable:

Relative URL links are very likely to break if you update the trailingSlash config

Maybe try links with .md extensions instead? Those work with the GitHub interface as well.

Also, the current behavior is correct: for a file at /docs/design/functions.md, its URL is /docs/design/functions/, so if you have a relative link code_and_name_organization, that would point to /docs/design/functions/code_and_name_organization according to how URLs are resolved.

[Josh-Cena]

@emlai Did you get to look at using Markdown links?

[slorber]

@emlai

When trailingSlash: true, a markdown link api file of a library in /docs/design/functions.md incorrectly navigates to /docs/design/functions/code_and_name_organization/#libraries. It should navigate to /docs/design/code_and_name_organization/#libraries.

We don't do anything with relative links in Docusaurus, we just render <a href="code_and_name_organization/#libraries"/> as is: it is your responsibility to provide a relative link that works with how browsers behave natively.

GitHub does not use trailing slashes. If you want better compatibility with GitHub I suggest not using trailing slashes either on Docusaurus.

When trailingSlash: false, a markdown link Language specification in /docs/spec/README.md incorrectly navigates to /docs/lang. It should navigate to /docs/spec/lang.

As explained, we don't process relative links in any way: it's just how browsers behave.

• <a href="lang"> will navigate to /docs/lang if current URL is /docs/spec
• <a href="lang"> will navigate to /docs/spec/lang if current URL is /docs/spec/
• <a href="lang"> will navigate to /docs/spec/lang if current URL is /docs/spec/readme

Important: we have a Docusaurus convention: by default /docs/spec/README.md will be hosted on /docs/spec and not /docs/spec/readme.

This convention + trailingSlash both affects your source page URL, and your source page url affects how your relative links are resolved (native browser behavior, it's not Docusaurus)

You can solve your issue by keeping trailingSlash: false and opting out of the convention with custom frontmatter: slug: /spec/readme => now your lang link will resolve to /docs/spec/lang

---

TLDR:

• Docusaurus does not do anything with relative links, it's native browser behavior
• When using relative links, things easily break. Make sure your source page has the correct URL because it affects the native resolution behavior

I also suggest using links with .md extensions => we'll process the extension in Docusaurus and replace it with the correct absolute URL of the page (with/without trailing slash). This works in GitHub and will self-update in case you decide to use slug: /xyz in the source/target document.

[octogonz]

@slorber Maybe we can improve this manual page: https://docusaurus.io/docs/markdown-features/links

Somehow I read that page several times without understanding that I need to be writing [thing](../path/thing.md) instead of [thing](../path/thing) or [thing](/path/thing).

Admittedly I was in a hurry and not reading each sentence carefully, or noticing the carefully italicized words. 😅

But from an editorial perspective, these docs would be more effective if they started by advising what to do instead of explaining how it works. As a new user, I'm not interested all the possible link syntaxes. I don't care why one option is better than another. Just tell me what to do clearly with examples -- and maybe include a "strict" mode that can report an error if one of our authors forgets the .md file extension, or uses the / leading slash.

Then, in a later section, there can be reference material for advanced users that explains the reasoning behind the recommendation, and other approaches that are possible.

[Josh-Cena]

Both are inevitable. Markdown links only work in one plugin so we definitely can't only speak about that, let alone issuing an error. I (as a tech writer myself) firmly believe it's important for you to see the bigger picture from the start especially when there's no silver bullet. That's the thing I find a lot of documentation annoyingly lack. I also know a lot of people who exclusively use absolute URL links, because URL links tend to be stable even when you move files around (you keep the slug or you add a redirect). It's simply impossible to say "you must use Markdown links" without letting you know what you are actually doing.

[slorber]

Yes, it's really hard to advocate for any ultimate way to link documents together.

Some links work in GitHub, some in Gitlab, some in Docusaurus, some with versioning, and some with i18n. At the end of the day, you have to find a linking pattern that suits your need regarding the features you use.

We do recommend relative file path links:

Maybe we should make this more visible? in an admonition tip?

[Josh-Cena]

Closing because the current behavior is correct.

Maybe we should make this more visible? in an admonition tip?

I think it's fine. https://twitter.com/ddbeck/status/1509925868021420042