Relative markdown links broken

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

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

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

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