Slash is added to paths when following link to page, making relative links invalid

[Sainan]

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.
• [ ] I have read the console error message carefully (if applicable).

Description

A relative link in the markdown such as the following:

[removes the restriction from them](../QoL%20Improvements/Reserved%20Identifiers)

Which can be seen live at https://pluto-lang.org/docs/For%20Developers/Compatibility breaks because visiting the page via a link causes there to be an additional / at the end of the URL, but using the sidebar to navigate to that page causes there to be no slash, so the relative link remains valid.

What is kind of weird is that I can't reproduce this issue locally, but it happens when hosted by GH pages, even on latest version.

Reproducible demo

No response

Steps to reproduce

1. Visit https://pluto-lang.org/docs/For%20Developers/Compatibility
2. Click on "removes the restriction from them"
3. Notice the "Page Not Found" error
4. Now manually navigate there by clicking "Introduction", "For Developers", "Compatbility"
5. Click on "removes the restriction from them"
6. Notice that this time the link worked

Expected behavior

No slash is added to the URL when clicking on a link, same as when visiting the page via the sidebar.

Actual behavior

A slash is added to the URL.

Your environment

• Public source code: https://github.com/PlutoLang/plutolang.github.io
• Public site URL: https://pluto-lang.org/
• Docusaurus version used: 2.0.0-beta.22
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Chrome 109.0.5414.75
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 10

Self-service

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

[Josh-Cena]

Please see https://docusaurus.io/docs/markdown-features/links and https://docusaurus.io/docs/deployment#trailing-slashes. Trailing slashes and relative links don't work well with each other on GH Pages; it's not something we can help as there's no Docusaurus machinery involved here.

[Sainan]

I have set trailingSlashes to false and look at that: I would argue the fact that by default you emit a directory for individual pages is just asking for this issue to occur. I would at the very least change the sidebar behaviour to also add the slash since it's expected of a web server to add the slash for a directory index.

[Josh-Cena]

trailingSlash: undefined means "let plugins do whatever they want", and even if we "fix" it in our docs plugin, you are going to run into similar issues sooner or later with other (possibly community) plugins. We don't try to be consistent with trailing slashes when producing links—there are numerous ways to end up with a trailing slash or miss one (for example, through the slug front matter), and normalization at this stage means scattering the logic across many places where we handle permalinks, so we only normalize once in the core when (a) creating routes and (b) emitting files.

This is a long-winded way to say "the trailingSlash config should align with your host and it's not really our concern to make things work without any explicit config", or put another way, "GH pages doesn't make your life easier because trailingSlash: undefined does work on Netlify/Vercel without any trouble" 😄

[Sainan]

Does trailingSlash: false cause issues with Netlify/Vercel, tho? Either way, not adding the slash to a directory index seems like a defect with that particular web server.

[slorber]

@Sainan if you want to understand the problem in depth you can read my analysis here and find out that all hosts have different behaviors when serving static files, and it's impossible to apply a default behavior that will always work for all of them at the same time: https://github.com/slorber/trailing-slash-guide

not adding the slash to a directory index seems like a defect with that particular web server.

it's expected of a web server to add the slash for a directory index.

Final URLs do not have to be correlated in any way with the directory structure. We have file-system conventions to make things convenient but remember that putting files under the /docs folder is not exactly like putting static files behind a traditional web server like Apache/Nginx or whatever you are used to. Modern static hosts do not always add a / for folders, it depends on the config. We don't particularly consider this as a defect or plan to change that behavior.

Does trailingSlash: false cause issues with Netlify/Vercel, tho?

Just read the deployment docs, we recommend trailingSlash configs for these hosts and you can refer to https://github.com/slorber/trailing-slash-guide if you want to understand better why.

[Sainan]

I did read that, and it seems to me like Vercel is the only web server causing you issues, whereas every other web server behaves as expected.