From 4e150d2b8247d44e964272e9a1a52a212d47ec01 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= <slorber@users.noreply.github.com>
Date: Thu, 19 Oct 2023 19:38:32 +0200
Subject: [PATCH] docs: add Docusaurus v3.0 upgrade guide (#9417)

---
 .../index.mdx                                 |   2 +-
 website/docs/advanced/plugins.mdx             |   2 +-
 .../docs/api/plugins/plugin-content-blog.mdx  |   4 +-
 website/docs/blog.mdx                         |  10 +-
 website/docs/deployment.mdx                   |   2 +-
 .../docs/guides/docs/docs-introduction.mdx    |   2 +-
 website/docs/i18n/i18n-crowdin.mdx            |   2 +-
 website/docs/i18n/i18n-tutorial.mdx           |   2 +-
 website/docs/introduction.mdx                 |  14 +-
 website/docs/migration/index.mdx              |  13 +
 .../{ => v2}/migration-automated.mdx          |   2 +-
 .../migration/{ => v2}/migration-manual.mdx   |  12 +-
 .../migration/{ => v2}/migration-overview.mdx |   4 +-
 .../{ => v2}/migration-translated-sites.mdx   |   8 +-
 .../{ => v2}/migration-versioned-sites.mdx    |   2 +-
 website/docs/migration/v3.mdx                 | 829 ++++++++++++++++++
 website/docs/styling-layout.mdx               |   2 +-
 website/sidebars.ts                           |  25 +-
 18 files changed, 896 insertions(+), 41 deletions(-)
 create mode 100644 website/docs/migration/index.mdx
 rename website/docs/migration/{ => v2}/migration-automated.mdx (98%)
 rename website/docs/migration/{ => v2}/migration-manual.mdx (97%)
 rename website/docs/migration/{ => v2}/migration-overview.mdx (98%)
 rename website/docs/migration/{ => v2}/migration-translated-sites.mdx (94%)
 rename website/docs/migration/{ => v2}/migration-versioned-sites.mdx (99%)
 create mode 100644 website/docs/migration/v3.mdx

diff --git a/website/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/index.mdx b/website/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/index.mdx
index 678dea498970..cd326b44bfdf 100644
--- a/website/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/index.mdx
+++ b/website/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/index.mdx
@@ -410,7 +410,7 @@ Upgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3.
 
 :::
 
-### React 18
+### React 18.0
 
 Docusaurus v3 now requires **React >= 18.0**.
 
diff --git a/website/docs/advanced/plugins.mdx b/website/docs/advanced/plugins.mdx
index e724c6214a18..1f09ea723a2a 100644
--- a/website/docs/advanced/plugins.mdx
+++ b/website/docs/advanced/plugins.mdx
@@ -1,6 +1,6 @@
 # Plugins
 
-Plugins are the building blocks of features in a Docusaurus 2 site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets.
+Plugins are the building blocks of features in a Docusaurus site. Each plugin handles its own individual feature. Plugins may work and be distributed as part of a bundle via presets.
 
 ## Creating plugins {#creating-plugins}
 
diff --git a/website/docs/api/plugins/plugin-content-blog.mdx b/website/docs/api/plugins/plugin-content-blog.mdx
index cfb7fe19df49..54d9b340a4a0 100644
--- a/website/docs/api/plugins/plugin-content-blog.mdx
+++ b/website/docs/api/plugins/plugin-content-blog.mdx
@@ -249,7 +249,7 @@ Example:
 
 ```md
 ---
-title: Welcome Docusaurus v2
+title: Welcome Docusaurus
 authors:
   - slorber
   - yangshun
@@ -258,7 +258,7 @@ authors:
     url: https://github.com/JoelMarcey
     image_url: https://github.com/JoelMarcey.png
 tags: [hello, docusaurus-v2]
-description: This is my first post on Docusaurus 2.
+description: This is my first post on Docusaurus.
 image: https://i.imgur.com/mErPwqL.png
 hide_table_of_contents: false
 ---
diff --git a/website/docs/blog.mdx b/website/docs/blog.mdx
index 8301c43efaf9..43a0c23a53d2 100644
--- a/website/docs/blog.mdx
+++ b/website/docs/blog.mdx
@@ -40,12 +40,12 @@ export default {
 
 To publish in the blog, create a Markdown file within the blog directory.
 
-For example, create a file at `website/blog/2019-09-05-hello-docusaurus-v2.md`:
+For example, create a file at `website/blog/2019-09-05-hello-docusaurus.md`:
 
-```md title="website/blog/2019-09-05-hello-docusaurus-v2.md"
+```md title="website/blog/2019-09-05-hello-docusaurus.md"
 ---
-title: Welcome Docusaurus v2
-description: This is my first post on Docusaurus 2.
+title: Welcome Docusaurus
+description: This is my first post on Docusaurus.
 slug: welcome-docusaurus-v2
 authors:
   - name: Joel Marcey
@@ -597,7 +597,7 @@ https://example.com/blog/feed.json
 
 ### Blog-only mode {#blog-only-mode}
 
-You can run your Docusaurus 2 site without a dedicated landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to serve the blog through the root route `example.com/` instead of the subroute `example.com/blog/`.
+You can run your Docusaurus site without a dedicated landing page and instead have your blog's post list page as the index page. Set the `routeBasePath` to be `'/'` to serve the blog through the root route `example.com/` instead of the subroute `example.com/blog/`.
 
 ```js title="docusaurus.config.js"
 export default {
diff --git a/website/docs/deployment.mdx b/website/docs/deployment.mdx
index 8936d1be484a..b91958e73e24 100644
--- a/website/docs/deployment.mdx
+++ b/website/docs/deployment.mdx
@@ -154,7 +154,7 @@ Because we can only provide this content on a best-effort basis only, we have st
 
 ## Deploying to Netlify {#deploying-to-netlify}
 
-To deploy your Docusaurus 2 sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
+To deploy your Docusaurus sites to [Netlify](https://www.netlify.com/), first make sure the following options are properly configured:
 
 ```js title="docusaurus.config.js"
 export default {
diff --git a/website/docs/guides/docs/docs-introduction.mdx b/website/docs/guides/docs/docs-introduction.mdx
index 0c52d173287a..3892c316be04 100644
--- a/website/docs/guides/docs/docs-introduction.mdx
+++ b/website/docs/guides/docs/docs-introduction.mdx
@@ -115,6 +115,6 @@ example.com/tutorial-basics/...    -> generated from `docs/tutorial-basics/...`
 
 :::tip
 
-There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).
+There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.mdx#blog-only-mode).
 
 :::
diff --git a/website/docs/i18n/i18n-crowdin.mdx b/website/docs/i18n/i18n-crowdin.mdx
index 22882cb9ed49..6c215106f714 100644
--- a/website/docs/i18n/i18n-crowdin.mdx
+++ b/website/docs/i18n/i18n-crowdin.mdx
@@ -501,7 +501,7 @@ It is currently **not possible to link to a specific file** in Crowdin.
 
 ### Example configuration {#example-configuration}
 
-The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance:
+The **Docusaurus configuration file** is a good example of using versioning and multi-instance:
 
 ```mdx-code-block
 import CrowdinConfigV2 from '!!raw-loader!@site/../crowdin-v2.yaml';
diff --git a/website/docs/i18n/i18n-tutorial.mdx b/website/docs/i18n/i18n-tutorial.mdx
index 6f22cf9a6c2d..b74896547cd7 100644
--- a/website/docs/i18n/i18n-tutorial.mdx
+++ b/website/docs/i18n/i18n-tutorial.mdx
@@ -470,7 +470,7 @@ You can now [deploy](../deployment.mdx) the `build` folder to the static hosting
 
 :::note
 
-The Docusaurus v2 website uses this strategy:
+The Docusaurus website uses this strategy:
 
 - [`https://docusaurus.io`](https://docusaurus.io)
 - [`https://docusaurus.io/fr`](https://docusaurus.io/fr)
diff --git a/website/docs/introduction.mdx b/website/docs/introduction.mdx
index db4e2caf58d7..f681afff861a 100644
--- a/website/docs/introduction.mdx
+++ b/website/docs/introduction.mdx
@@ -68,11 +68,11 @@ import LiteYouTubeEmbed from 'react-lite-youtube-embed';
 
 ## Migrating from v1 {#migrating-from-v1}
 
-Docusaurus v2 has been a total rewrite from Docusaurus v1, taking advantage of a completely modernized toolchain. After [v2's official release](https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0), we highly encourage you to **use Docusaurus v2 over Docusaurus v1**, as Docusaurus v1 has been deprecated.
+Docusaurus v2+ has been a total rewrite from Docusaurus v1, taking advantage of a completely modernized toolchain. After [v2's official release](https://docusaurus.io/blog/2022/08/01/announcing-docusaurus-2.0), we highly encourage you to **use Docusaurus v2+ over Docusaurus v1**, as Docusaurus v1 has been deprecated.
 
-A [lot of users](/showcase) are already using Docusaurus v2 ([trends](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)).
+A [lot of users](/showcase) are already using Docusaurus v2+ ([trends](https://www.npmtrends.com/docusaurus-vs-@docusaurus/core)).
 
-**Use Docusaurus v2 if:**
+**Use Docusaurus v2+ if:**
 
 - :white_check_mark: You want a modern Jamstack documentation site
 - :white_check_mark: You want a single-page application (SPA) with client-side routing
@@ -84,7 +84,7 @@ A [lot of users](/showcase) are already using Docusaurus v2 ([trends](https://ww
 - :x: You don't want a single-page application (SPA)
 - :x: You need support for IE11 (...do you? IE [has already reached end-of-life](https://docs.microsoft.com/en-us/lifecycle/products/internet-explorer-11) and is no longer officially supported)
 
-For existing v1 users that are seeking to upgrade to v2, you can follow our [migration guide](./migration/migration-overview.mdx).
+For existing v1 users that are seeking to upgrade to v2+, you can follow our [migration guides](./migration/index.mdx).
 
 ## Features {#features}
 
@@ -115,9 +115,9 @@ Our shared goal—to help your users quickly find what they need and understand
 - 💾 **Document Versioning**: Helps you keep documentation in sync with project releases.
 - 🌍 **Internationalization (i18n)**: Translate your site in multiple locales.
 
-Docusaurus 2 is born to be compassionately accessible to all your users, and lightning-fast.
+Docusaurus v2+ is born to be compassionately accessible to all your users, and lightning-fast.
 
-- ⚡️ **Lightning-fast**. Docusaurus 2 follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast.
+- ⚡️ **Lightning-fast**. Docusaurus v2+ follows the [PRPL Pattern](https://developers.google.com/web/fundamentals/performance/prpl-pattern/) that makes sure your content loads blazing fast.
 - 🦖 **Accessible**. Attention to accessibility, making your site equally accessible to all users.
 
 ## Design principles {#design-principles}
@@ -142,7 +142,7 @@ We've also studied other main static site generators and would like to share our
 
 GraphQL is also pretty core to Gatsby, although you don't necessarily need GraphQL to build a Gatsby site. In most cases when building static websites, you won't need the flexibility that GraphQL provides.
 
-Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and it's a great alternative.
+Many aspects of Docusaurus v2+ were inspired by the best things about Gatsby and it's a great alternative.
 
 [Docz](https://github.com/pedronauck/docz) is a Gatsby theme to build documentation websites. It is currently less featured than Docusaurus.
 
diff --git a/website/docs/migration/index.mdx b/website/docs/migration/index.mdx
new file mode 100644
index 000000000000..c78662f032eb
--- /dev/null
+++ b/website/docs/migration/index.mdx
@@ -0,0 +1,13 @@
+---
+slug: /migration
+---
+
+# Upgrading Docusaurus
+
+Docusaurus versioning is based on the `major.minor.patch` scheme and respects [**Semantic Versioning**](https://semver.org/).
+
+**Breaking changes** are only released on major version upgrades, and thoroughly documented in the following upgrade guides.
+
+import DocCardList from '@theme/DocCardList';
+
+<DocCardList />
diff --git a/website/docs/migration/migration-automated.mdx b/website/docs/migration/v2/migration-automated.mdx
similarity index 98%
rename from website/docs/migration/migration-automated.mdx
rename to website/docs/migration/v2/migration-automated.mdx
index 93c41ae8863f..61e07cc4c1f5 100644
--- a/website/docs/migration/migration-automated.mdx
+++ b/website/docs/migration/v2/migration-automated.mdx
@@ -1,5 +1,5 @@
 ---
-slug: /migration/automated
+slug: /migration/v2/automated
 ---
 
 # Automated migration
diff --git a/website/docs/migration/migration-manual.mdx b/website/docs/migration/v2/migration-manual.mdx
similarity index 97%
rename from website/docs/migration/migration-manual.mdx
rename to website/docs/migration/v2/migration-manual.mdx
index 904e2611449c..0d733b1d42be 100644
--- a/website/docs/migration/migration-manual.mdx
+++ b/website/docs/migration/v2/migration-manual.mdx
@@ -1,5 +1,5 @@
 ---
-slug: /migration/manual
+slug: /migration/v2/manual
 toc_max_heading_level: 4
 ---
 
@@ -455,7 +455,7 @@ If you had `cleanUrl: false` in v1, it's possible that people published links to
 
 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](../api/plugins/plugin-client-redirects.mdx) to create client-side redirects from `/installation.html` to `/installation`.
+As an escape hatch, you could use [@docusaurus/plugin-client-redirects](../../api/plugins/plugin-client-redirects.mdx) to create client-side redirects from `/installation.html` to `/installation`.
 
 ```js
 module.exports = {
@@ -476,7 +476,7 @@ If you want to keep the `.html` extension as the canonical URL of a page, docs c
 
 ### Sidebar {#sidebar}
 
-In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../guides/docs/sidebar/items.mdx) other than document.
+In previous version, nested sidebar category is not allowed and sidebar category can only contain doc ID. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](../../guides/docs/sidebar/items.mdx) other than document.
 
 You'll have to migrate your sidebar if it contains category type. Rename `subcategory` to `category` and `ids` to `items`.
 
@@ -492,7 +492,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
 
 ### Footer {#footer}
 
-`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../swizzling.mdx) it:
+`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../../swizzling.mdx) it:
 
 ```bash npm2yarn
 npm run swizzle @docusaurus/theme-classic Footer
@@ -573,7 +573,7 @@ The following code could be helpful for migration of various pages:
 
 ### Replace AUTOGENERATED_TABLE_OF_CONTENTS {#replace-autogenerated_table_of_contents}
 
-This feature is replaced by [inline table of content](../guides/markdown-features/markdown-features-toc.mdx#inline-table-of-contents)
+This feature is replaced by [inline table of content](../../guides/markdown-features/markdown-features-toc.mdx#inline-table-of-contents)
 
 ### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible}
 
@@ -585,7 +585,7 @@ Front matter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-ma
 
 ### Language-specific code tabs {#language-specific-code-tabs}
 
-Refer to the [multi-language support code blocks](../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section.
+Refer to the [multi-language support code blocks](../../guides/markdown-features/markdown-features-code-blocks.mdx#multi-language-support-code-blocks) section.
 
 ### Front matter {#front-matter}
 
diff --git a/website/docs/migration/migration-overview.mdx b/website/docs/migration/v2/migration-overview.mdx
similarity index 98%
rename from website/docs/migration/migration-overview.mdx
rename to website/docs/migration/v2/migration-overview.mdx
index 59a8102c26db..b917c4067504 100644
--- a/website/docs/migration/migration-overview.mdx
+++ b/website/docs/migration/v2/migration-overview.mdx
@@ -1,8 +1,8 @@
 ---
-slug: /migration
+slug: /migration/v2
 ---
 
-# Migration overview
+# Overview
 
 This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
 
diff --git a/website/docs/migration/migration-translated-sites.mdx b/website/docs/migration/v2/migration-translated-sites.mdx
similarity index 94%
rename from website/docs/migration/migration-translated-sites.mdx
rename to website/docs/migration/v2/migration-translated-sites.mdx
index ddc48fd3b820..79df1299a0e8 100644
--- a/website/docs/migration/migration-translated-sites.mdx
+++ b/website/docs/migration/v2/migration-translated-sites.mdx
@@ -1,5 +1,5 @@
 ---
-slug: /migration/translated-sites
+slug: /migration/v2/translated-sites
 ---
 
 # Translated sites
@@ -79,8 +79,8 @@ This documentation is a best-effort to help you migrate, please help us improve
 Before all, we recommend to:
 
 - Migrate your v1 Docusaurus site to v2 without the translations
-- Get familiar with the [new i18n system of Docusaurus v2](../i18n/i18n-introduction.mdx) an
-- Make Crowdin work for your v2 site, using a new and untranslated Crowdin project and the [Crowdin tutorial](../i18n/i18n-crowdin.mdx)
+- Get familiar with the [new i18n system of Docusaurus v2](../../i18n/i18n-introduction.mdx) an
+- Make Crowdin work for your v2 site, using a new and untranslated Crowdin project and the [Crowdin tutorial](../../i18n/i18n-crowdin.mdx)
 
 :::danger
 
@@ -124,7 +124,7 @@ You might want to repeat this pre-translation process, eventually trying the "Pe
 
 :::tip
 
-Use [`mdx-code-block`](../i18n/i18n-crowdin.mdx#mdx-solutions) around problematic Markdown elements: Crowdin is less likely mess things up with code blocks.
+Use [`mdx-code-block`](../../i18n/i18n-crowdin.mdx#mdx-solutions) around problematic Markdown elements: Crowdin is less likely mess things up with code blocks.
 
 :::
 
diff --git a/website/docs/migration/migration-versioned-sites.mdx b/website/docs/migration/v2/migration-versioned-sites.mdx
similarity index 99%
rename from website/docs/migration/migration-versioned-sites.mdx
rename to website/docs/migration/v2/migration-versioned-sites.mdx
index 3e145d38f268..c4a799025d5b 100644
--- a/website/docs/migration/migration-versioned-sites.mdx
+++ b/website/docs/migration/v2/migration-versioned-sites.mdx
@@ -1,5 +1,5 @@
 ---
-slug: /migration/versioned-sites
+slug: /migration/v2/versioned-sites
 ---
 
 # Versioned sites
diff --git a/website/docs/migration/v3.mdx b/website/docs/migration/v3.mdx
new file mode 100644
index 000000000000..1e79672ac8e5
--- /dev/null
+++ b/website/docs/migration/v3.mdx
@@ -0,0 +1,829 @@
+---
+slug: /migration/v3
+sidebar_label: To Docusaurus v3
+---
+
+# Upgrading to Docusaurus v3
+
+This documentation will help you upgrade your site from Docusaurus v2 to Docusaurus v3.
+
+Docusaurus v3 is a new **major version**, including **breaking changes** requiring you to adjust your site accordingly. We will guide to during this process, and also mention a few optional recommendations.
+
+This is not a full rewrite, and the breaking changes are relatively easy to handle. The simplest sites will eventually upgrade by simply updating their npm dependencies.
+
+The main breaking change is the [**upgrade to MDX v2**](https://mdxjs.com/blog/v2/), which will compile your Markdown content **more strictly** and with **subtle differences**.
+
+:::tip Before upgrading
+
+Before upgrading, we recommend [**preparing your site for Docusaurus v3**](/blog/preparing-your-site-for-docusaurus-v3). There are changes that you can already **handle incrementally, under Docusaurus v2**. Doing so will help reduce the work needed to finally upgrade to Docusaurus v3.
+
+For complex sites, we also recommend to set up [**visual regression tests**](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing), a good way to ensure your site stays visually identical. Docusaurus v3 mainly upgrades dependencies, and is not expected to produce any visual changes.
+
+:::
+
+:::note
+
+Check the release notes for [**Docusaurus v3.0.0**](https://github.com/facebook/docusaurus/releases/tag/v3.0.0), and browse the pull-requests for additional useful information and the motivation behind each change mentioned here.
+
+:::
+
+## Upgrading Dependencies
+
+Upgrading to Docusaurus v3 requires upgrading core Docusaurus dependencies (`@docusaurus/name`), but also other related packages.
+
+Docusaurus v3 now uses the following dependencies:
+
+- Node.js v18.0+
+- React v18.0+
+- MDX v2.0+
+- TypeScript v5.0+
+- prism-react-renderer v2.0+
+- react-live v4.0+
+- mermaid v10.4+
+
+:::warning Upgrading community plugins
+
+If your site uses third-party community plugins and themes, you might need to upgrade them.
+
+Make sure those plugins are compatible with Docusaurus v3 before attempting an upgrade.
+
+:::
+
+A typical `package.json` dependency upgrade example:
+
+```diff title="package.json"
+ {
+   "dependencies": {
+     // upgrade to Docusaurus v3
+-    "@docusaurus/core": "2.4.3",
+-    "@docusaurus/preset-classic": "2.4.3",
++    "@docusaurus/core": "3.0.0",
++    "@docusaurus/preset-classic": "3.0.0",
+     // upgrade to MDX v2
+-    "@mdx-js/react": "^1.6.22",
++    "@mdx-js/react": "^2.3.0",
+     // upgrade to prism-react-renderer v2.0+
+-    "prism-react-renderer": "^1.3.5",
++    "prism-react-renderer": "^2.1.0",
+     // upgrade to React v18.0+
+-    "react": "^17.0.2",
+-    "react-dom": "^17.0.2"
++    "react": "^18.2.0",
++    "react-dom": "^18.2.0"
+   },
+   "devDependencies": {
+     // upgrade Docusaurus dev dependencies to v3
+-    "@docusaurus/module-type-aliases": "2.4.3"
+-    "@docusaurus/types": "2.4.3"
++    "@docusaurus/module-type-aliases": "3.0.0"
++    "@docusaurus/types": "3.0.0"
+   }
+   "engines": {
+     // require Node.js 18.0+
+-    "node": ">=16.14"
++    "node": ">=18.0"
+   }
+ }
+```
+
+For TypeScript users:
+
+```diff title="package.json"
+ {
+   "devDependencies": {
+     // swap the external TypeScript config package for the new official one
+-    "@tsconfig/docusaurus": "^1.0.7",
++    "@docusaurus/tsconfig": "3.0.0",
+     // upgrade React types to v18.0+
+-    "@types/react": "^17.0.69",
++    "@types/react": "^18.2.29",
+     // upgrade TypeScript to v5.0+
+-    "typescript": "~4.7.4"
++    "typescript": "~5.2.2"
+   }
+ }
+```
+
+## Upgrading MDX
+
+MDX is a major dependency of Docusaurus responsible for compiling your `.md` and `.mdx` files to React components.
+
+The transition from MDX v1 to MDX v2 is the **main challenge** to the adoption of Docusaurus v3.
+
+Some documents that compiled successfully under Docusaurus v2 might now **fail to compile** under Docusaurus v3.
+
+:::tip Find problematic content ahead of time
+
+Run [`npx docusaurus-mdx-checker`](https://github.com/slorber/docusaurus-mdx-checker) on your site to get a list of files that will now fail to compile under Docusaurus v3.
+
+This command is also a good way to estimate the amount of work to be done to make your content compatible. Remember most of this work can be executed ahead of the upgrade by [preparing your content for Docusaurus v3](/blog/preparing-your-site-for-docusaurus-v3).
+
+:::
+
+Other documents might also **render differently**.
+
+:::tip Use visual regression tests
+
+For large sites where a manual review of all pages is complicated, we recommend you to setup [visual regression tests](https://docusaurus.io/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing).
+
+:::
+
+Upgrading MDX comes with all the breaking changes documented on the [MDX v2 release blog post](https://mdxjs.com/blog/v2/). The [MDX v2 migration guide](https://mdxjs.com/migrating/v2/) has a section on how to [update MDX files](https://mdxjs.com/migrating/v2/#update-mdx-files) that will be particularly relevant to us. Also make sure to read the [Troubleshooting MDX](https://mdxjs.com/docs/troubleshooting-mdx/) page that can help you interpret common MDX error messages.
+
+Make sure to also read our updated [**MDX and React**](../guides/markdown-features/markdown-features-react.mdx) documentation page.
+
+### Using the MDX playground
+
+The MDX playground is your new best friend. It permits to understand how your content is **compiled to React components**, and troubleshoot compilation or rendering issues in isolation.
+
+Each MDX version comes with its own playground:
+
+- [MDX v1 playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground/)
+- [MDX v2 playground](https://mdxjs.com/playground/)
+
+<details>
+  <summary>Configuring the MDX v2 playground options for Docusaurus</summary>
+
+To obtain a compilation behavior similar to what Docusaurus v2 uses, please turn on these options on the [MDX v2 playground](https://mdxjs.com/playground/):
+
+- Use `MDX`
+- Use `remark-gfm`
+- Use `remark-directive`
+
+![Screenshot of the MDX v2 playground's options panel, with only the "Use `MDX`", "Use `remark-gfm`", and "Use `remark-directive`" options checked](@site/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/img/mdx2-playground-options.png)
+
+</details>
+
+Using the two MDX playgrounds side-by-side, you will soon notice that some content is compiled differently or fails to compile in v2.
+
+:::tip Making your content future-proof
+
+The goal will be to refactor your problematic content so that it **works fine with both versions of MDX**. This way, when you upgrade to Docusaurus v3, this content will already work out-of-the-box.
+
+:::
+
+### Using the MDX checker CLI
+
+We provide a [docusaurus-mdx-checker](https://github.com/slorber/docusaurus-mdx-checker) CLI that permits to easily spot problematic content. Run this command on your site to obtain a list of files that will fail to compile under MDX v2.
+
+```bash
+npx docusaurus-mdx-checker
+```
+
+For each compilation issue, the CLI will log the file path and a line number to look at.
+
+![Screenshot of the terminal showing an example MDX checker CLI output, with a few error messages](@site/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/img/mdx-checker-output.png)
+
+:::tip
+
+Use this CLI to estimate of how much work will be required to make your content compatible with MDX v2.
+
+:::
+
+:::warning
+
+This CLI is a best effort, and will **only report compilation errors**.
+
+It will not report subtle compilation changes that do not produce errors but can affect how your content is displayed. To catch these problems, we recommend using [visual regression tests](/blog/upgrading-frontend-dependencies-with-confidence-using-visual-regression-testing).
+
+:::
+
+### Common MDX problems
+
+Docusaurus cannot document exhaustively all the changes coming with MDX v2. That's the responsibility of the [MDX v2 migration guide](https://mdxjs.com/migrating/v2/).
+
+However, by upgrading a few Docusaurus sites, we noticed that most of the issues come down to only a few cases that we have documented for you.
+
+#### Bad usage of `{`
+
+The `{` character is used for opening [JavaScript expressions](https://mdxjs.com/docs/what-is-mdx/#expressions). MDX v2 will now fail if what you put inside `{expression}` is not a valid expression.
+
+```md title="example.md"
+The object shape looks like {username: string, age: number}
+```
+
+:::danger Error message
+
+> Could not parse expression with acorn: Unexpected content after expression
+
+:::
+
+:::tip How to upgrade
+
+Available options to fix this error:
+
+- Use inline code: `{username: string, age: number}`
+- Use the HTML code: `&#123;`
+- Escape it: `\{`
+
+:::
+
+#### Bad usage of `<`
+
+The `<` character is used for opening [JSX tags](https://mdxjs.com/docs/what-is-mdx/#jsx). MDX v2 will now fail if it thinks your JSX is invalid.
+
+```md title="example.md"
+Use Android version <5
+
+You can use a generic type like Array<T>
+
+Follow the template "Road to <YOUR_MINOR_VERSION>"
+```
+
+:::danger Error messages
+
+> Unexpected character `5` (U+0035) before name, expected a character that can start a name, such as a letter, `$`, or `_`
+
+> Expected a closing tag for `<T>` (1:6-1:9) before the end of `paragraph` end-tag-mismatch mdast-util-mdx-jsx
+
+> Expected a closing tag for `<YOUR_MINOR_VERSION>` (134:19-134:39) before the end of `paragraph`
+
+:::
+
+:::tip How to upgrade
+
+Available options to fix this error:
+
+- Use inline code: `Array<T>`
+- Use the HTML code: `&lt;` or `&#60;`
+- Escape it: `\<`
+
+:::
+
+#### Bad usage of GFM Autolink
+
+Docusaurus supports [GitHub Flavored Markdown (GFM)](https://github.github.com/gfm/), but [autolink](https://github.github.com/gfm/#autolinks) using the `<link>` syntax is not supported anymore by MDX v2.
+
+```md title="example.md"
+<sebastien@thisweekinreact.com>
+
+<http://localhost:3000>
+```
+
+:::danger Error messages
+
+> Unexpected character `@` (U+0040) in name, expected a name character such as letters, digits, `$`, or `_`; whitespace before attributes; or the end of the tag (note: to create a link in MDX, use `[text](url)`)
+
+> Unexpected character `/` (U+002F) before local name, expected a character that can start a name, such as a letter, `$`, or `_` (note: to create a link in MDX, use `[text](url)`)
+
+:::
+
+:::tip How to upgrade
+
+Use regular Markdown links, or remove the `<` and `>`. MDX and GFM are able to autolink literals already.
+
+{/* prettier-ignore */}
+```md title="example.md"
+sebastien@thisweekinreact.com
+[sebastien@thisweekinreact.com](mailto:sebastien@thisweekinreact.com)
+
+http://localhost:3000
+[http://localhost:3000](http://localhost:3000)
+```
+
+:::
+
+#### Lower-case MDXComponent mapping
+
+For users providing a [custom `MDXComponent`mapping](../guides/markdown-features/markdown-features-react.mdx#mdx-component-scope), components are now "sandboxed":
+
+- a `MDXComponent` mapping for `h1` only gets used for `# hi` but not for `<h1>hi</h1>`
+- a **lower-cased** custom element name will not be substituted by its respective `MDXComponent` component anymore
+
+:::danger visual difference
+
+Your [`MDXComponent` component mapping](/docs/3.0.0-beta.0/markdown-features/react#mdx-component-scope) might not be applied as before, and your custom components might no longer be used.
+
+:::
+
+:::tip How to upgrade
+
+For native Markdown elements, you can keep using **lower-case**: `p`, `h1`, `img`, `a`...
+
+For any other element, **use upper-case names**.
+
+```diff title="src/theme/MDXComponents.js"
+ import MDXComponents from '@theme-original/MDXComponents';
+
+ export default {
+   ...MDXComponents,
+   p: (props) => <p {...props} className="my-paragraph"/>
+-  myElement: (props) => <div {...props} className="my-class" />,
++  MyElement: (props) => <div {...props} className="my-class" />,
+ };
+```
+
+:::
+
+#### Unintended extra paragraphs
+
+In MDX v2, it is now possible to interleave JSX and Markdown more easily without requiring extra line breaks. Writing content on multiple lines can also produce new expected `<p>` tags.
+
+:::danger visual difference
+
+See how this content is rendered differently by MDX v1 and v2.
+
+```md title="example.md"
+<div>Some **Markdown** content</div>
+<div>
+  Some **Markdown** content
+</div>
+```
+
+{/* prettier-ignore */}
+```html title="MDX v1 output"
+<div>Some **Markdown** content</div>
+<div>Some **Markdown** content</div>
+```
+
+{/* prettier-ignore */}
+```html title="MDX v2 output"
+<div>Some <strong>Markdown</strong> content</div>
+<div><p>Some <strong>Markdown</strong> content</p></div></div>
+```
+
+:::
+
+:::tip How to upgrade
+
+If you don't want an extra `<p>` tag, refactor content on a case by case basis to use a single-line JSX tag.
+
+```diff
+ <figure>
+   <img src="/img/myImage.png" alt="My alt" />
+-  <figcaption>
+-    My image caption
+-  </figcaption>
++  <figcaption>My image caption</figcaption>
+ </figure>
+```
+
+:::
+
+#### Unintended usage of directives
+
+Docusaurus v3 now uses [Markdown Directives](https://talk.commonmark.org/t/generic-directives-plugins-syntax/444) (implemented with [remark-directive](https://github.com/remarkjs/remark-directive)) as a generic way to provide support for admonitions, and other upcoming Docusaurus features.
+
+```md title="example.md"
+This is a :textDirective
+
+::leafDirective
+
+:::containerDirective
+
+Container directive content
+
+:::
+```
+
+:::danger Visual change
+
+Directives are parsed with the purpose of being handled by other Remark plugins. Unhandled directives will be ignored, and won't be rendered back in their original form.
+
+```md title="example.md"
+The AWS re:Invent conf is great
+```
+
+Due to `:Invent` being parsed as a text directive, this will now be rendered as:
+
+```
+The AWS re
+conf is great
+```
+
+:::
+
+:::tip How to upgrade
+
+- Use the HTML code: `&#58;`
+- Add a space after `:` (if it makes sense): `: text`
+- Escape it: `\:`
+
+:::
+
+#### Unsupported indented code blocks
+
+MDX v2 does not transform indented text as code blocks anymore.
+
+```md title="example.md"
+    console.log("hello");
+```
+
+:::danger Visual change
+
+The upgrade does not generally produce new MDX v2 compilation errors, but can lead to content being rendered in an unexpected way because there isn't a code block anymore.
+
+:::
+
+:::tip How to upgrade
+
+Use the regular code block syntax instead of indentation:
+
+````md title="example.md"
+```js
+console.log('hello');
+```
+````
+
+:::
+
+### MDX plugins
+
+All the official packages (Unified, Remark, Rehype...) in the MDX ecosystem are now [**ES Modules only**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c) and do not support [CommonJS](https://nodejs.org/api/modules.html#modules-commonjs-modules) anymore.
+
+In practice this means that you can't do `require("remark-plugin")` anymore.
+
+:::tip How to upgrade
+
+Docusaurus v3 now supports [**ES Modules**](https://flaviocopes.com/es-modules/) configuration files. We recommend that you migrate your config file to ES module, that enables you to import the Remark plugins easily:
+
+```js title="docusaurus.config.js"
+import remarkPlugin from 'remark-plugin';
+
+export default {
+  title: 'Docusaurus',
+  /* site config using remark plugins here */
+};
+```
+
+If you want to keep using CommonJS modules, you can use dynamic imports as a workaround that enables you to import ES modules inside a CommonJS module. Fortunately, the [Docusaurus config supports the usage of an async function](/docs/configuration#syntax-to-declare-docusaurus-config) to let you do so.
+
+```js title="docusaurus.config.js"
+module.exports = async function () {
+  const myPlugin = (await import('remark-plugin')).default;
+  return {
+    // site config...
+  };
+};
+```
+
+:::
+
+:::info For plugin authors
+
+If you created custom Remark or Rehype plugins, you may need to refactor those, or eventually rewrite them completely, due to how the new AST is structured. We have created a [dedicated support discussion](https://github.com/facebook/docusaurus/discussions/9337) to help plugin authors upgrade their code.
+
+:::
+
+## Other Breaking Changes
+
+Apart the MDX v2 upgrade, here is an exhaustive list of breaking changes coming with Docusaurus v3.
+
+### Node.js v18.0
+
+Node.js 16 [reached End-of-Life](https://nodejs.org/en/blog/announcements/nodejs16-eol), and Docusaurus v3 now requires **Node.js >= 18.0**.
+
+:::tip How to upgrade
+
+Install Node.js 18.0+ on your computer.
+
+Eventually, configure your continuous integration, CDN or host to use this new Node.js version.
+
+You can also update your site `package.json` to prevent usage of an older unsupported version:
+
+```diff title="package.json"
+ {
+   "engines": {
+-     "node": ">=16.14"
++     "node": ">=18.0"
+   }
+ }
+```
+
+Upgrade your Docusaurus v2 site to Node.js 18 before upgrading to Docusaurus v3.
+
+:::
+
+### React v18.0+
+
+Docusaurus v3 now requires **React >= 18.0**.
+
+React 18 comes with its own breaking changes that should be relatively easy to handle, depending on the amount of custom React code you created for your site. The official themes and plugins are compatible with React 18.
+
+:::info How to upgrade
+
+Read the official [React v18.0](https://react.dev/blog/2022/03/29/react-v18) and [How to Upgrade to React 18](https://react.dev/blog/2022/03/08/react-18-upgrade-guide), and look at your own React code to figure out which components might be affected this upgrade.
+
+We recommend to particularly look for:
+
+- Automatic batching for stateful components
+- New React hydration errors reported to the console
+
+:::
+
+:::danger Experimental support for React 18 features
+
+React 18 comes with new features:
+
+- `<Suspense>`
+- `React.lazy()`
+- `startTransition`
+
+Their Docusaurus support is considered as experimental. We might have to adjust the integration in the future, leading to a different runtime behavior.
+
+:::
+
+### Prism-React-Renderer v2.0+
+
+Docusaurus v3 upgrades [`prism-react-renderer`](https://github.com/FormidableLabs/prism-react-renderer) to v2.0+. This library is used for code block syntax highlighting.
+
+:::info How to upgrade
+
+This is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. The [`prism-react-renderer` v2 release notes](https://github.com/FormidableLabs/prism-react-renderer/releases/tag/prism-react-renderer%402.0.0) are not super exhaustive, but there are 3 major changes to be aware of for Docusaurus users.
+
+The dependency should be upgraded:
+
+```diff title="package.json"
+ {
+   "dependencies": {
+-    "prism-react-renderer": "^1.3.5",
++    "prism-react-renderer": "^2.1.0",
+ }
+```
+
+The API to import themes in your Docusaurus config file has been updated:
+
+```diff title="docusaurus.config.js"
+- const lightTheme = require('prism-react-renderer/themes/github');
+- const darkTheme = require('prism-react-renderer/themes/dracula');
++ const {themes} = require('prism-react-renderer');
++ const lightTheme = themes.github;
++ const darkTheme = themes.dracula;
+```
+
+Previously, `react-prism-render` v1 [included more languages by default](https://github.com/FormidableLabs/prism-react-renderer/blob/v1.3.5/src/vendor/prism/includeLangs.js). From v2.0+, [less languages are included by default](https://github.com/FormidableLabs/prism-react-renderer/blob/prism-react-renderer%402.1.0/packages/generate-prism-languages/index.ts#L9). You may need to add extra languages to your Docusaurus config:
+
+```js title="docusaurus.config.js"
+const siteConfig = {
+  themeConfig: {
+    prism: {
+      // highlight-next-line
+      additionalLanguages: ['bash', 'diff', 'json'],
+    },
+  },
+};
+```
+
+:::
+
+### React-Live v4.0+
+
+For users of the `@docusaurus/theme-live-codeblock` package, Docusaurus v3 upgrades [`react-live`](https://github.com/FormidableLabs/react-live) to v4.0+.
+
+:::info How to upgrade
+
+In theory, you have nothing to do, and your existing interactive code blocks should keep working as before.
+
+However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the [v3](https://github.com/FormidableLabs/react-live/releases/tag/v3.0.0) and [v4](https://github.com/FormidableLabs/react-live/releases/tag/v4.0.0) changelogs in case of problems.
+
+:::
+
+### Mermaid v10.4+
+
+For users of the `@docusaurus/theme-mermaid` package, Docusaurus v3 upgrades [`mermaid`](https://github.com/mermaid-js/mermaid) to v10.4+.
+
+:::info How to upgrade
+
+In theory, you have nothing to do, and your existing diagrams should keep working as before.
+
+However, this is a new major library version containing breaking changes, and we can't guarantee a strict retro-compatibility. Read the [v10](https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0) changelog in case of problem.
+
+:::
+
+### TypeScript v5.0+
+
+Docusaurus v3 now requires **TypeScript >= 5.0**.
+
+:::info How to upgrade
+
+Upgrade your dependencies to use TypeScript 5+
+
+```diff title="package.json"
+ {
+   "devDependencies": {
+-    "typescript": "~4.7.4"
++    "typescript": "~5.2.2"
+   }
+ }
+```
+
+:::
+
+### TypeScript base config
+
+The official Docusaurus TypeScript config has been re-internalized from the external package [`@tsconfig/docusaurus`](https://www.npmjs.com/package/@tsconfig/docusaurus) to our new monorepo package [`@docusaurus/tsconfig`](https://www.npmjs.com/package/@docusaurus/tsconfig).
+
+This new package is versioned alongside all the other Docusaurus core packages, and will be used to ensure TypeScript retro-compatibility and breaking changes on major version upgrades.
+
+:::info How to upgrade
+
+Swap the external TypeScript config package for the new official one
+
+```diff title="package.json"
+ {
+   "devDependencies": {
+-    "@tsconfig/docusaurus": "^1.0.7",
++    "@docusaurus/tsconfig": "3.0.0",
+   }
+ }
+```
+
+Use it in your `tsconfig.json` file:
+
+```diff title="tsconfig.json"
+ {
+-  "extends": "@tsconfig/docusaurus/tsconfig.json",
++  "extends": "@docusaurus/tsconfig",
+   "compilerOptions": {
+     "baseUrl": "."
+   }
+ }
+```
+
+:::
+
+### New Config Loader
+
+Docusaurus v3 changes its internal config loading library from [`import-fresh`](https://github.com/sindresorhus/import-fresh) to [`jiti`](https://github.com/unjs/jiti). It is responsible for loading files such as `docusaurus.config.js` or `sidebars.js`, and Docusaurus plugins.
+
+:::info How to upgrade
+
+In theory, you have nothing to do, and your existing config files should keep working as before.
+
+However, this is a major dependency swap and subtle behavior changes could occur.
+
+:::
+
+### Admonition Warning
+
+For historical reasons, we support an undocumented admonition `:::warning` that renders with a red color.
+
+:::danger Warning
+
+This is a Docusaurus v2 `:::warning` admonition.
+
+:::
+
+However, the color and icon have always been wrong. Docusaurus v3 re-introduces `:::warning` admonition officially, documents it, and fix the color and icon.
+
+:::warning
+
+This is a Docusaurus v3 `:::warning` admonition.
+
+:::
+
+:::info How to upgrade
+
+If you previously used the undocumented `:::warning` admonition, make sure to verify for each usage if yellow is now an appropriate color. If you want to keep the red color, use `:::danger` instead.
+
+Docusaurus v3 also [deprecated the `:::caution`](https://github.com/facebook/docusaurus/pull/9308) admonition. Please refactor `:::caution` (yellow) to either `:::warning` (yellow) or `:::danger` (red).
+
+:::
+
+### Versioned Sidebars
+
+This breaking change will only affect **Docusaurus v2 early adopters** who versioned their docs before `v2.0.0-beta.10` (December 2021).
+
+When creating version `v1.0.0`, the sidebar file contained a prefix `version-v1.0.0/` that [Docusaurus v3 does not support anymore](https://github.com/facebook/docusaurus/pull/9310).
+
+```json title="versioned_sidebars/version-v1.0.0-sidebars.json"
+{
+  "version-v1.0.0/docs": [
+    "version-v1.0.0/introduction",
+    "version-v1.0.0/prerequisites"
+  ]
+}
+```
+
+:::info How to upgrade
+
+Remove the useless versioned prefix from your versioned sidebars.
+
+```json title="versioned_sidebars/version-v1.0.0-sidebars.json"
+{
+  "docs": ["introduction", "prerequisites"]
+}
+```
+
+:::
+
+### Blog Feed Limit
+
+The `@docusaurus/plugin-content-blog` now limits the RSS feed to the last 20 entries by default. For large Docusaurus blogs, this is a more sensible default value to avoid an increasingly large RSS file.
+
+:::info How to upgrade
+
+In case you don't like this new default behavior, you can revert to the former "unlimited feed" behavior with the new `limit: false` feed option:
+
+```js title="docusaurus.config.js"
+const blogOptions = {
+  feedOptions: {
+    // highlight-next-line
+    limit: false,
+  },
+};
+```
+
+:::
+
+### Docs Theme Refactoring
+
+For users that swizzled docs-related theme components (like `@theme/DocPage`), these components have been significantly refactor to make it easier to customize.
+
+Technically, **this is not a breaking change** because these components are **flagged as unsafe to swizzle**, however many Docusaurus sites ejected docs-related components, and will be interested to know their customizations might break Docusaurus.
+
+:::info How to upgrade
+
+Delete all your swizzled components, re-swizzle them, and re-apply your customizations on top of the newly updated components.
+
+Alternatively, you can look at the [pull-request notes](https://github.com/facebook/docusaurus/pull/7966) to understand the new theme component tree structure, and eventually try to patch your swizzled components manually.
+
+:::
+
+## Optional Changes
+
+Some changes are not mandatory, but remain useful to be aware of to plainly leverage Docusaurus v3.
+
+### Automatic JSX runtime
+
+Docusaurus v3 now uses the React 18 ["automatic" JSX runtime](https://legacy.reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html).
+
+It is not needed anymore to import React in JSX files that do not use any React API.
+
+```diff title="src/components/MyComponent.js"
+- import React from 'react';
+
+  export default function MyComponent() {
+    return <div>Hello</div>;
+  }
+```
+
+### ESM and TypeScript Configs
+
+Docusaurus v3 supports ESM and TypeScript config files, and it might be a good idea to adopt those new options.
+
+```js title="docusaurus.config.js"
+export default {
+  title: 'Docusaurus',
+  url: 'https://docusaurus.io',
+  // your site config ...
+};
+```
+
+```ts title="docusaurus.config.ts"
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'My Site',
+  favicon: 'img/favicon.ico',
+  presets: [
+    [
+      'classic',
+      {
+        /* Your preset config here */
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    /* Your theme config here */
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;
+```
+
+### Using the `.mdx` extension
+
+We recommend using the `.mdx` extension whenever you use JSX, `import`, or `export` (i.e. MDX features) inside a Markdown file. It is semantically more correct and improves compatibility with external tools (IDEs, formatters, linters, etc.).
+
+In future versions of Docusaurus, `.md` files will be parsed as standard [CommonMark](https://commonmark.org/), which does not support these features. In Docusaurus v3, `.md` files keep being compiled as MDX files, but it will be possible to [opt-in for CommonMark](https://github.com/facebook/docusaurus/issues/3018).
+
+## Ask For Help
+
+In case of any upgrade problem, the first things to try are:
+
+- make sure all your docs compile in the [MDX v2 playground](https://mdxjs.com/playground/), or using [`npx docusaurus-mdx-checker`](https://github.com/slorber/docusaurus-mdx-checker)
+- delete `node_modules` and run `npm install` again
+- run `docusaurus clear` to clear the caches
+- remove third-party plugins that might not support Docusaurus v3
+- delete all your swizzled components
+
+Once you have tried that, you can ask for support through the following support channels:
+
+- [Docusaurus v3 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9336)
+- [Docusaurus v3 - Discord channel #migration-v2-to-v3](https://discord.com/channels/398180168688074762/1154771869094912090)
+- [MDX v2 - Upgrade Support](https://github.com/facebook/docusaurus/discussions/9053)
+- [MDX v2 - Remark/Rehype Plugins Support](https://github.com/facebook/docusaurus/discussions/9337)
+- [MDX v2 - Discord channel #migration-mdx-v2](https://discord.com/channels/398180168688074762/1116724556976111616)
+
+Please consider **our time is precious**. To ensure that your support request is not ignored, we kindly ask you to:
+
+- provide a **minimal** reproduction that we can easily run, ideally created with [docusaurus.new](https://docusaurus.new)
+- provide a live deployment url showing the problem in action (if your site can build)
+- explain clearly the problem, much more than an ambiguous "it doesn't work"
+- include as much relevant material as possible: code snippets, repo url, git branch urls, full stack traces, screenshots and videos
+- present your request clearly, concisely, showing us that you have made an effort to help us help you
+
+Alternatively, you can look for a paid [Docusaurus Service Provider](https://github.com/facebook/docusaurus/discussions/9281) to execute this upgrade for you. If your site is open source, you can also ask our community for [free, benevolent help](https://github.com/facebook/docusaurus/discussions/9283).
diff --git a/website/docs/styling-layout.mdx b/website/docs/styling-layout.mdx
index 21e5d15719ba..369c688ea51a 100644
--- a/website/docs/styling-layout.mdx
+++ b/website/docs/styling-layout.mdx
@@ -223,7 +223,7 @@ CSS-in-JS support is a work in progress, so libs like MUI may have display quirk
 
 ## Sass/SCSS {#sassscss}
 
-To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus 2 plugin [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass). This plugin works for both global styles and the CSS modules approach:
+To use Sass/SCSS as your CSS preprocessor, install the unofficial Docusaurus plugin [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass). This plugin works for both global styles and the CSS modules approach:
 
 1. Install [`docusaurus-plugin-sass`](https://github.com/rlamana/docusaurus-plugin-sass):
 
diff --git a/website/sidebars.ts b/website/sidebars.ts
index 0b7b39b51e5a..09ddffdb7784 100644
--- a/website/sidebars.ts
+++ b/website/sidebars.ts
@@ -132,13 +132,26 @@ const sidebars: SidebarsConfig = {
     },
     {
       type: 'category',
-      label: 'Migrating from v1 to v2',
+      label: 'Upgrading',
+      link: {
+        type: 'doc',
+        id: 'migration/index',
+      },
       items: [
-        'migration/migration-overview',
-        'migration/migration-automated',
-        'migration/migration-manual',
-        'migration/migration-versioned-sites',
-        'migration/migration-translated-sites',
+        'migration/v3',
+        // TODO do we want to keep upgrade docs for older Docusaurus versions?
+        // It contains links to docs of current version :/
+        {
+          type: 'category',
+          label: 'To Docusaurus v2',
+          items: [
+            'migration/v2/migration-overview',
+            'migration/v2/migration-automated',
+            'migration/v2/migration-manual',
+            'migration/v2/migration-versioned-sites',
+            'migration/v2/migration-translated-sites',
+          ],
+        },
       ],
     },
   ],