docs: add Docusaurus v3.0 upgrade guide (#9417)

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**.
 

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}
 

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
 ---

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 {

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 {

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).
 
 :::

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';

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)

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.
 

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 />

website/docs/migration/migration-automated.mdx → website/docs/migration/v2/migration-automated.mdx

@@ -1,5 +1,5 @@
 ---
-slug: /migration/automated
+slug: /migration/v2/automated
 ---
 
 # Automated migration

website/docs/migration/migration-manual.mdx → 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}
 

website/docs/migration/migration-overview.mdx → 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.
 

website/docs/migration/migration-translated-sites.mdx → 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.
 
 :::
 

website/docs/migration/migration-versioned-sites.mdx → website/docs/migration/v2/migration-versioned-sites.mdx

@@ -1,5 +1,5 @@
 ---
-slug: /migration/versioned-sites
+slug: /migration/v2/versioned-sites
 ---
 
 # Versioned sites