Enable clean / extension-less url

[endiliey]

Motivation

Closes #413

This is a feature request in issue #413, and #478 (comment)

Some of Docosaurus URL look very cryptic/un-clean. Instead of blog/a.html, blog/b.html, and blog/c.html, user should be able to choose if they prefer to see blog/a, blog/b and blog/c

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

• New config cleanUrl in siteConfig.js,
  If true, all linking from each page will be without .html except custom pages that has hardcoded linking value.

Before:

After:

• yarn start will allow extension-less url (server routing)
  Which means request to docs/a.html is the same as docs/a
  Test yarn start server routing on development server

cd website
yarn start

http://localhost:3000/docs/en/installation

http://localhost:3000/docs/en/installation.html

• yarn build will generate extra file when cleanUrl at siteConfig.js is true

Test yarn build to see generated files

cd website
yarn build
tree -a -I "css|CNAME|.circleci|img|js" build/Docusaurus/ > build.txt

Results are expected
Full generated files structure can be seen at https://gist.github.com/endiliey/cd184c237bc1c0b544677ad19cc8ece7

build/Docusaurus/
├── about-slash
│   └── index.html
├── about-slash.html
├── blog
│   ├── 2017
│   │   └── 12
│   │       └── 14
│   │           ├── introducing-docusaurus
│   │           │   └── index.html
│   │           └── introducing-docusaurus.html

├── docs
│   ├── 1.0.11
│   │   ├── api-pages
│   │   │   └── index.html
│   │   ├── api-pages.html

• Test production build (static files) in local webserver using https://www.npmjs.com/package/serve

cd website
yarn build
serve build/Docosaurus

http://localhost:5000/docs/en/site-preparation

http://localhost:5000/docs/en/site-preparation.html

http://localhost:5000/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus

http://localhost:5000/blog/2018/04/30/How-I-Converted-Profilo-To-Docusaurus.html

http://localhost:5000/en/about-slash

http://localhost:5000/en/about-slash.html

All seems to be working fine. Every url is accessible with and without .html

Alternatively, you can test production build in Netlify
https://deploy-preview-677--docusaurus-preview.netlify.com/

[docusaurus-bot]

Deploy preview for docusaurus-preview ready!

Built with commit 52376f0

https://deploy-preview-677--docusaurus-preview.netlify.com

[ericnakagawa]

This is a neat feature. Thanks for supporting the old urls as well!

[yansern]

Just tried this out myself while I was testing the other non-related issue! Great work!

[JoelMarcey]

@endiliey Excellent! Looks like others have tested it too, which always makes me feel better about a bigger change like this 😄

Are you ready for this to go in? If so, I will update the branch and we can merge.

@yangshun Are you good?

[endiliey]

I am not in a rush with this PR, i'm out of reach from my laptop until this weekend because i'm currently hospitalized. But i have tested it on dev & prod build in local web server before and there is no problem yet.

But note that custom pages (e.g: pages/en/index.js) with hardcoded link still link to docs/installation.html

https://github.com/facebook/Docusaurus/blob/a603aff193096195bd805b5755f662d981d0857e/website/pages/en/index.js#L51

Do we want to change it to extension-less one ?

[JoelMarcey]

Hi @endiliey

I am not in a rush with this PR, i'm out of reach from my laptop until this weekend because i'm currently hospitalized.

Best wishes to you. 🙏

But note that custom pages (e.g: pages/en/index.js) with hardcoded link still link to docs/installation.html

We can change those in a separate PR, I think.

[endiliey]

I am ready anytime. I'll leave it to your decision. Waiting for @yangshun approval is also a good idea 😉

[yangshun]

I'll give it a thorough look tonight! One concern I have is that will the blog comments will show different contents depending on whether it's the index.html version or the clean URL version? Not sure if FB treats them as canonical URLs.

[endiliey]

I just tested that and it is actually the same url. Regardless of .html or /index.html or /. The data-href from facebook comment is not the current url and always point to the clean url (if siteConfig cleanUrl is true)

I just added 'Wow, awesome' to one of the blog comment in netlify preview and you can see it in all three url ☺

https://deploy-preview-677--docusaurus-preview.netlify.com/blog/2017/12/14/introducing-docusaurus/index.html

https://deploy-preview-677--docusaurus-preview.netlify.com/blog/2017/12/14/introducing-docusaurus.html

https://deploy-preview-677--docusaurus-preview.netlify.com/blog/2017/12/14/introducing-docusaurus/

[JoelMarcey]

This is awesome! Thanks!

One suggestion. And we can get a second stamp from @yangshun.

[JoelMarcey]

Can you move this up to be alphabetical with the rest of the optional fields?

[endiliey]

I can. But i'm out of reach from my pc until this weekend. I'll do it later if you don't mind. Sorry!

[JoelMarcey]

Oh - no worries. I can do it for you 👍

[endiliey]

PR updated. Rebased on top of 1.1.5

Not sure if we want to remove the hardcoded linking values in Docusaurus custom pages if this is merged. Example:
https://github.com/facebook/Docusaurus/blob/b7be85843af2a07ead183dd8a467ebcf83e9a3e3/website/pages/en/index.js#L51

https://github.com/facebook/Docusaurus/blob/b7be85843af2a07ead183dd8a467ebcf83e9a3e3/website/pages/en/index.js#L117

[yangshun]

@endiliey Could we try to come up with a way to reduce the amount of duplication in the code?

[endiliey]

@yangshun refactor done ! Sorry for the wait. I've tested this on Windows as well.

[JoelMarcey]

Let's do this!