Fix trailing slash issues (depend on hosting provider)

Edit: as part of the analysis to solve this issue, I’m writing a guide to describe factually the behavior of various static site generators and static hosting providers: https://github.com/slorber/trailing-slash-guide

💥 Proposal

Fix trailing host slash issues: write /myDoc.html instead of /myDoc/index.html

We have a few issues that are related to docs trailing slashes: #2654, #2394, #2134, #3351, #3380

I suspect these issues are related to the Docusaurus output, as for a doc at /docs/myDoc we write /myDoc/index.html instead of /myDoc.html

Always creating a subfolder is probably a signal for the hosting providers (Netlify, Github Pages…) to add a trailing slash automatically to URLs, which can be annoying.

It can break relative links as now the link resolution is different due to the trailing slash, and we end up with broken links in production, not catched at build time (see https://github.com/facebook/docusaurus/issues/3380)

This behavior is provided by a dependency: https://github.com/markdalgleish/static-site-generator-webpack-plugin/blob/master/index.js#L165

We already run on a fork of this dependency. I guess we could as well include a way to write /myDoc.html directly if a route path does not end with a trailing slash.

As this is a risky change, I suggest making this optional. We can make it the default behavior (breaking change) later if it works fine for early adopters.

See also https://github.com/facebook/docusaurus/issues/2394

[slorber]

Just to make it clear: this issue is important for Docusaurus to solve and we’ll work on it. It is just not as simple as you might think it is.

Doing a fix that works for a single site is not hard.

But doing a fix that works for ALL Docusaurus sites, using a large variety of hosting providers, all with distinct behaviors regarding how they serve static files, is complicated.

And a bad fix deployed in production can lead to unwanted side-effects that negatively affect the SEO of established documentation websites and products, so we must be sure the changes we make are safe.

Note: the Gatsby ecosystem has the exact same trailing slash problem (we have some code in common). See for example this recent blog post: https://jonsully.net/blog/trailing-slashes-and-gatsby/

For me, the source of all this is this function in an unmaintained dependency: https://github.com/markdalgleish/static-site-generator-webpack-plugin/blob/master/index.js#L165 Changing this logic is easy (fork the dep and patch it). Ensuring it does not produce unwanted side effects is time-consuming to check.

---

My plan is to provide a fix for trailing slash issues as an option:

• existing sites keep the previous behavior (safe)
• you can turn the option on if you encounter the trailing slash / relative links problem
• newly initialized sites can have the option turned on

Unfortunately, this won’t prevent existing sites to not have issues unless they turn the option on.

If this option is successful for everyone, we could turn it on by default (the risky part)

---

Note: until I provide this option, the workaround I suggest here should work, and is not too far from what I plan to implement. So please try this workaround and tell us if it works or not.

[slorber]

The PR has been merged, and you can try this right now with the @canary dist tag or wait for beta.1

https://www.npmjs.com/package/@docusaurus/core?activeTab=versions

2.0.0-beta.df8a900f9

Please let me know if anything does not work asap.

Also, in general, can you please let me know:

• which host you had a problem with
• which trailingSlash setting fixed the problem

According to your feedbacks, we may update the doc and recommend a trailingSlash setting for each host