Merge pull request #2793 from slorber/feature/client-side-redirects

feat(v2): docusaurus-plugin-client-redirects

website/docs/migrating-from-v1-to-v2.md

@@ -448,6 +448,43 @@ The following fields are all deprecated, you may remove from your configuration
 
 We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
 
+## Urls
+
+In v1, all pages were available with or without the `.html` extension.
+
+For example, these 2 pages exist:
+
+- [https://docusaurus.io/docs/en/installation](https://docusaurus.io/docs/en/installation)
+- [https://docusaurus.io/docs/en/installation.html](https://docusaurus.io/docs/en/installation.html)
+
+If [`cleanUrl`](https://docusaurus.io/docs/en/site-config#cleanurl-boolean) was:
+
+- `true`: links would target `/installation`
+- `false`: links would target `/installation.html`
+
+In v2, by default, the canonical page is `/installation`, and not `/installation.html`.
+
+If you had `cleanUrl: false` in v1, it's possible that people published links to `/installation.html`.
+
+For SEO reasons, and avoiding breaking links, you should configure server-side redirect rules on your hosting provider.
+
+As an escape hatch, you could use [@docusaurus/plugin-client-redirects](./using-plugins.md#docusaurusplugin-client-redirects) to create client-side redirects from `/installation.html` to `/installation`.
+
+```js
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        fromExtensions: ['html'],
+      },
+    ],
+  ],
+};
+```
+
+If you want to keep the `.html` extension as the canonical url of a page, docs can declare a `slug: installation.html` frontmatter.
+
 ## Components
 
 ### Sidebar

website/docs/using-plugins.md

@@ -458,3 +458,123 @@ import thumbnail from './path/to/img.png';
 | `max` | `integer` |  | See `min` above |
 | `steps` | `integer` | `4` | Configure the number of images generated between `min` and `max` (inclusive) |
 | `quality` | `integer` | `85` | JPEG compression quality |
+
+### `@docusaurus/plugin-client-redirects`
+
+Docusaurus Plugin to generate **client-side redirects**.
+
+This plugin will write additional HTML pages to your static site, that redirects the user to your existing Docusaurus pages with JavaScript.
+
+:::caution
+
+It is better to use server-side redirects whenever possible.
+
+Before using this plugin, you should look if your hosting provider doesn't offer this feature.
+
+:::
+
+**Installation**
+
+```bash npm2yarn
+npm install --save @docusaurus/plugin-client-redirects
+```
+
+**Configuration**
+
+Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this page from `/myDocusaurusPage.html`:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        fromExtensions: ['html'],
+      },
+    ],
+  ],
+};
+```
+
+Second usecase: you have `/myDocusaurusPage.html`, and you want to redirect to this page from `/myDocusaurusPage`.
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        toExtensions: ['html'],
+      },
+    ],
+  ],
+};
+```
+
+For custom redirect logic, provide your own `createRedirects` function.
+
+Let's imagine you change the url of an existing page, you might want to make sure the old url still works:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        redirects: [
+          {
+            to: '/docs/newDocPath', // string
+            from: ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016'], // string | string[]
+          },
+        ],
+      },
+    ],
+  ],
+};
+```
+
+It's possible to use a function to create the redirects for each existing path:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        createRedirects: function (existingPath) {
+          if (existingPath === '/docs/newDocPath') {
+            return ['/docs/oldDocPathFrom2019', '/docs/legacyDocPathFrom2016']; // string | string[]
+          }
+        },
+      },
+    ],
+  ],
+};
+```
+
+Finally, it's possible to use all options at the same time:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  plugins: [
+    [
+      '@docusaurus/plugin-client-redirects',
+      {
+        fromExtensions: ['html', 'htm'],
+        toExtensions: ['exe', 'zip'],
+        redirects: [
+          {
+            to: '/docs/newDocPath',
+            from: '/docs/oldDocPath',
+          },
+        ],
+        createRedirects: function (existingPath) {
+          if (existingPath === '/docs/newDocPath2') {
+            return ['/docs/oldDocPath2'];
+          }
+        },
+      },
+    ],
+  ],
+};
+```