From b8168e22876ed5fa4f0cf931d67ac2047f146df7 Mon Sep 17 00:00:00 2001
From: slorber <lorber.sebastien@gmail.com>
Date: Mon, 1 Jun 2020 17:32:55 +0200
Subject: [PATCH] document @docusaurus/plugin-client-redirects in migration
 guide + fix doc typo

---
 website/docs/migrating-from-v1-to-v2.md | 37 +++++++++++++++++++++++++
 website/docs/using-plugins.md           |  6 ++--
 2 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md
index 4b5e23c162..07ce3e1667 100644
--- a/website/docs/migrating-from-v1-to-v2.md
+++ b/website/docs/migrating-from-v1-to-v2.md
@@ -420,6 +420,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` suffix.
+
+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',
+      {
+        fromExtension: ['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
diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md
index 1504c51ede..9526105d14 100644
--- a/website/docs/using-plugins.md
+++ b/website/docs/using-plugins.md
@@ -489,7 +489,7 @@ Main usecase: you have `/myDocusaurusPage`, and you want to redirect to this pag
 module.exports = {
   plugins: [
     [
-      '@docusaurus/plugin-sitemap',
+      '@docusaurus/plugin-client-redirects',
       {
         fromExtension: ['html'],
       },
@@ -504,7 +504,7 @@ Second usecase: you have `/myDocusaurusPage.html`, and you want to redirect to t
 module.exports = {
   plugins: [
     [
-      '@docusaurus/plugin-sitemap',
+      '@docusaurus/plugin-client-redirects',
       {
         toExtension: ['html'],
       },
@@ -521,7 +521,7 @@ Let's imagine you change the url of an pexisting age, you might want to make sur
 module.exports = {
   plugins: [
     [
-      '@docusaurus/plugin-sitemap',
+      '@docusaurus/plugin-client-redirects',
       {
         createRedirects: function (existingPath) {
           if (existingPath === '/docs/newDocPath') {