Docusaurus v2 doesn't allow for "mypagename.html" links

We migrated and now have a series of issues being raised because none of our 7 year old links ending in .html resolve correctly.

This is the main issue tracking this: https://github.com/facebook/watchman/issues/798

A couple of kind souls have submitted PRs to change links elsewhere: https://github.com/facebook/watchman/pull/806 https://github.com/facebook/watchman/pull/801

but this is really a docusaurus issue. How can we get this fixed?

[slorber]

Hi @wez , sorry for the delay.

Just wanted to let you know that the fixes you need are already merged on master and will be released soon in 2.0.0-alpha.57

---

What you will need to do on Watchman:

add a slug to each doc

With the extension you want, which will be used for the main/canonical/SEO url

---
id: nodejs
slug: nodejs.html
title: NodeJS
---

Use the client redirects plugin

Plugin doc

Your configuration should look like:

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-client-redirects',
      {
        toExtensions: ['html'],
      },
    ],
  ],
};

And if there exist a /docs/nodejs.html page, then going to /docs/nodejs will redirect to /docs/nodejs.html

[slorber]

Hi all,

Here are a few comments, proposals and questions I have

Valid urls of Watchman

I understand that such url should work:

• https://facebook.github.io/watchman/docs/nodejs.html

Does it mean that BOTH urls should work?

• https://facebook.github.io/watchman/docs/nodejs
• https://facebook.github.io/watchman/docs/nodejs.html

I don’t know how Watchman site worked before, is it still online somewhere to check?

Hosting on Github pages

Watchman is hosted on Github pages. As far as I know, it’s not possible to do any server-side redirect on this hosting solution.

Also, for Github pages to serve a non-404 answer, the file actually has to exist on the FS with the html extension.

On other platforms like netlify, it would have been posssible to drop a simple _redirects file and handle this.

It might be a good idea to start using a custom domain, which would allow more flexibility to change the underlying hosting solution without too much pain.

Using .html extension in document id

If Watchman just need the /nodejs.html, and not the /nodejs page, it’s possible to use .html as suffix in document ids

Using a file like filename.html.md also works

duplicating the pages

Creating 2 html pages for the same document could be a portable solution

---
id: nodejs
extraPaths: 
  - nodejs.htm
  - nodejs.html
title: NodeJS page
---

The duplicate pages would have a canonical url to the main page so that SEO can know which page is the main one.

Is it worth redirecting in this case? or can the browser just stay on the non-canonical page if it serves the correct content?

404 + redirecting

This looks like the solution @lex111 implemented here: https://github.com/facebook/docusaurus/pull/2704 Which was not merged due to SEO reasons related to serving 404.

I found this note here: https://github.com/rafrex/spa-github-pages

A quick SEO note - while it’s never good to have a 404 response, it appears based on Search Engine Land’s testing that Google’s crawler will treat the JavaScript window.location redirect in the 404.html file the same as a 301 redirect for its indexing. From my testing I can confirm that Google will index all pages without issue, the only caveat is that the redirect query is what Google indexes as the url. For example, the url example.tld/about will get indexed as example.tld/?p=/about. When the user clicks on the search result, the url will change back to example.tld/about once the site loads.

I’d prefer not to do that as well but that remains an option.

---

What do you think?