chore: v3.0.0-rc.0 release (#9418)

website/blog/2023-09-29-preparing-your-site-for-docusaurus-v3/index.mdx

@@ -49,7 +49,7 @@ MDX v2 is much better, but also comes with changes that probably require you to
 
 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**](/docs/3.0.0-beta.0/markdown-features/react) documentation page.
+Make sure to also read our updated [**MDX and React**](/docs/3.0.0-rc.0/markdown-features/react) documentation page.
 
 :::tip Ask for help
 
@@ -214,14 +214,14 @@ http://localhost:3000
 
 #### Lower-case MDXComponent mapping
 
-For users providing a [custom `MDXComponent`mapping](/docs/3.0.0-beta.0/markdown-features/react#mdx-component-scope), components are now "sandboxed":
+For users providing a [custom `MDXComponent`mapping](/docs/3.0.0-rc.0/markdown-features/react#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.
+Your [`MDXComponent` component mapping](/docs/3.0.0-rc.0/markdown-features/react#mdx-component-scope) might not be applied as before, and your custom components might no longer be used.
 
 :::
 

website/docs/migration/v3.mdx

@@ -292,7 +292,7 @@ For users providing a [custom `MDXComponent`mapping](../guides/markdown-features
 
 :::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.
+Your [`MDXComponent` component mapping](/docs/3.0.0-rc.0/markdown-features/react#mdx-component-scope) might not be applied as before, and your custom components might no longer be used.
 
 :::
 

website/package.json

@@ -1,6 +1,6 @@
 {
   "name": "website",
-  "version": "3.0.0-beta.0",
+  "version": "3.0.0-rc.0",
   "private": true,
   "scripts": {
     "docusaurus": "docusaurus",
@@ -36,19 +36,19 @@
   "dependencies": {
     "@crowdin/cli": "^3.13.0",
     "@crowdin/crowdin-api-client": "^1.23.3",
-    "@docusaurus/core": "3.0.0-beta.0",
-    "@docusaurus/logger": "3.0.0-beta.0",
-    "@docusaurus/plugin-client-redirects": "3.0.0-beta.0",
-    "@docusaurus/plugin-ideal-image": "3.0.0-beta.0",
-    "@docusaurus/plugin-pwa": "3.0.0-beta.0",
-    "@docusaurus/preset-classic": "3.0.0-beta.0",
-    "@docusaurus/remark-plugin-npm2yarn": "3.0.0-beta.0",
-    "@docusaurus/theme-classic": "3.0.0-beta.0",
-    "@docusaurus/theme-common": "3.0.0-beta.0",
-    "@docusaurus/theme-live-codeblock": "3.0.0-beta.0",
-    "@docusaurus/theme-mermaid": "3.0.0-beta.0",
-    "@docusaurus/utils": "3.0.0-beta.0",
-    "@docusaurus/utils-common": "3.0.0-beta.0",
+    "@docusaurus/core": "3.0.0-rc.0",
+    "@docusaurus/logger": "3.0.0-rc.0",
+    "@docusaurus/plugin-client-redirects": "3.0.0-rc.0",
+    "@docusaurus/plugin-ideal-image": "3.0.0-rc.0",
+    "@docusaurus/plugin-pwa": "3.0.0-rc.0",
+    "@docusaurus/preset-classic": "3.0.0-rc.0",
+    "@docusaurus/remark-plugin-npm2yarn": "3.0.0-rc.0",
+    "@docusaurus/theme-classic": "3.0.0-rc.0",
+    "@docusaurus/theme-common": "3.0.0-rc.0",
+    "@docusaurus/theme-live-codeblock": "3.0.0-rc.0",
+    "@docusaurus/theme-mermaid": "3.0.0-rc.0",
+    "@docusaurus/utils": "3.0.0-rc.0",
+    "@docusaurus/utils-common": "3.0.0-rc.0",
     "@popperjs/core": "^2.11.8",
     "@swc/core": "1.2.197",
     "clsx": "^1.2.1",
@@ -83,8 +83,8 @@
     ]
   },
   "devDependencies": {
-    "@docusaurus/eslint-plugin": "3.0.0-beta.0",
-    "@docusaurus/tsconfig": "3.0.0-beta.0",
+    "@docusaurus/eslint-plugin": "3.0.0-rc.0",
+    "@docusaurus/tsconfig": "3.0.0-rc.0",
     "@types/color": "^3.0.4",
     "@types/jest": "^29.5.3",
     "cross-env": "^7.0.3",

website/versioned_docs/version-3.0.0-rc.0/advanced/architecture.mdx

@@ -20,7 +20,7 @@ This diagram shows how Docusaurus works to build your app. Plugins each collect
 
 Although you (either plugin authors or site creators) are writing JavaScript all the time, bear in mind that the JS is actually run in different environments:
 
-- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as CommonJS that can be `require`'d.
+- All plugin lifecycle methods are run in Node. Therefore, until we support ES Modules in our codebase, plugin source code must be provided as ES modules that can be imported, or CommonJS that can be `require`'d.
 - The theme code is built with Webpack. They can be provided as ESM—following React conventions.
 
 Plugin code and theme code never directly import each other: they only communicate through protocols (in our case, through JSON temp files and calls to `addRoute`). A useful mental model is to imagine that the plugins are not written in JavaScript, but in another language like Rust. The only way to interact with plugins for the user is through `docusaurus.config.js`, which itself is run in Node (hence you can use `require` and pass callbacks as plugin options).

website/versioned_docs/version-3.0.0-rc.0/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}
 
@@ -11,7 +11,7 @@ A plugin is a function that takes two parameters: `context` and `options`. It re
 You can use a plugin as a function directly included in the Docusaurus config file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: [
     // highlight-start
@@ -38,7 +38,7 @@ module.exports = {
 You can use a plugin as a module path referencing a separate file or npm package:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: [
     // without options:
@@ -52,7 +52,7 @@ module.exports = {
 Then in the folder `my-plugin`, you can create an `index.js` such as this:
 
 ```js title="my-plugin/index.js"
-module.exports = async function myPlugin(context, options) {
+export default async function myPlugin(context, options) {
   // ...
   return {
     name: 'my-plugin',
@@ -64,7 +64,7 @@ module.exports = async function myPlugin(context, options) {
     },
     /* other lifecycle API */
   };
-};
+}
 ```
 
 ---
@@ -99,7 +99,7 @@ This is a contrived example: in practice, `@docusaurus/theme-classic` provides t
 :::
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // highlight-next-line
   themes: ['theme-blog'],
   plugins: ['plugin-content-blog'],
@@ -109,7 +109,7 @@ module.exports = {
 And if you want to use Bootstrap styling, you can swap out the theme with `theme-blog-bootstrap` (another fictitious non-existing theme):
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // highlight-next-line
   themes: ['theme-blog-bootstrap'],
   plugins: ['plugin-content-blog'],

website/versioned_docs/version-3.0.0-rc.0/api/docusaurus.config.js.mdx

@@ -18,12 +18,20 @@ Refer to the Getting Started [**Configuration**](../configuration.mdx) for examp
 
 `docusaurus.config.js` contains configurations for your site and is placed in the root directory of your site.
 
-This file is run in Node.js using the [**CommonJS**](https://flaviocopes.com/commonjs/) module system, and should export a site configuration object, or a function that creates it.
+This file is run in Node.js and should export a site configuration object, or a function that creates it.
+
+The `docusaurus.config.js` file supports:
+
+- [**ES Modules**](https://flaviocopes.com/es-modules/)
+- [**CommonJS**](https://flaviocopes.com/commonjs/)
+- [**TypeScript**](../typescript-support.mdx#typing-config)
+
+hey
 
 Examples:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   title: 'Docusaurus',
   url: 'https://docusaurus.io',
   // your site config ...
@@ -31,13 +39,13 @@ module.exports = {
 ```
 
 ```js title="docusaurus.config.js"
-module.exports = async function createConfigAsync() {
+export default async function createConfigAsync() {
   return {
     title: 'Docusaurus',
     url: 'https://docusaurus.io',
     // your site config ...
   };
-};
+}
 ```
 
 :::tip
@@ -55,7 +63,7 @@ Refer to [**Syntax to declare `docusaurus.config.js`**](../configuration.mdx#syn
 Title for your website. Will be used in metadata and as browser tab title.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   title: 'Docusaurus',
 };
 ```
@@ -67,7 +75,7 @@ module.exports = {
 URL for your website. This can also be considered the top-level hostname. For example, `https://facebook.github.io` is the URL of https://facebook.github.io/metro/, and `https://docusaurus.io` is the URL for https://docusaurus.io. This field is related to the [`baseUrl`](#baseUrl) field.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   url: 'https://docusaurus.io',
 };
 ```
@@ -79,7 +87,7 @@ module.exports = {
 Base URL for your site. Can be considered as the path after the host. For example, `/metro/` is the base URL of https://facebook.github.io/metro/. For URLs that have no path, the baseUrl should be set to `/`. This field is related to the [`url`](#url) field. Always has both leading and trailing slash.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   baseUrl: '/',
 };
 ```
@@ -93,7 +101,7 @@ module.exports = {
 Path to your site favicon; must be a URL that can be used in link's href. For example, if your favicon is in `static/img/favicon.ico`:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   favicon: '/img/favicon.ico',
 };
 ```
@@ -127,7 +135,7 @@ Example:
 {/* cSpell:ignore فارسی */}
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fa'],
@@ -171,7 +179,7 @@ This option adds `<meta name="robots" content="noindex, nofollow">` to every pag
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   noIndex: true, // Defaults to `false`
 };
 ```
@@ -213,7 +221,7 @@ By default, it displays a warning after you run `yarn start` or `yarn build`.
 The tagline for your website.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   tagline:
     'Docusaurus makes it easy to maintain Open Source documentation websites.',
 };
@@ -226,7 +234,7 @@ module.exports = {
 The GitHub user or organization that owns the repository. You don't need this if you are not using the `docusaurus deploy` command.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // Docusaurus' organization is facebook
   organizationName: 'facebook',
 };
@@ -239,7 +247,7 @@ module.exports = {
 The name of the GitHub repository. You don't need this if you are not using the `docusaurus deploy` command.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   projectName: 'docusaurus',
 };
 ```
@@ -251,7 +259,7 @@ module.exports = {
 The name of the branch to deploy the static files to. You don't need this if you are not using the `docusaurus deploy` command.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   deploymentBranch: 'gh-pages',
 };
 ```
@@ -263,7 +271,7 @@ module.exports = {
 The hostname of your server. Useful if you are using GitHub Enterprise. You don't need this if you are not using the `docusaurus deploy` command.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   githubHost: 'github.com',
 };
 ```
@@ -275,7 +283,7 @@ module.exports = {
 The port of your server. Useful if you are using GitHub Enterprise. You don't need this if you are not using the `docusaurus deploy` command.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   githubPort: '22',
 };
 ```
@@ -289,7 +297,7 @@ The [theme configuration](./themes/theme-configuration.mdx) object to customize
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     docs: {
       sidebar: {
@@ -358,7 +366,7 @@ type PluginConfig = string | [string, any] | PluginModule | [PluginModule, any];
 See [plugin method references](./plugin-methods/README.mdx) for the shape of a `PluginModule`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     'docusaurus-plugin-awesome',
     ['docusuarus-plugin-confetti', {fancy: false}],
@@ -376,7 +384,7 @@ module.exports = {
 - Type: `PluginConfig[]`
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themes: ['@docusaurus/theme-classic'],
 };
 ```
@@ -390,7 +398,7 @@ type PresetConfig = string | [string, any];
 ```
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [],
 };
 ```
@@ -426,7 +434,7 @@ type MarkdownConfig = {
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   markdown: {
     format: 'mdx',
     mermaid: true,
@@ -464,7 +472,7 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add a custom fi
 - Type: `Object`
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   customFields: {
     admin: 'endi',
     superman: 'lol',
@@ -487,7 +495,7 @@ An array of paths, relative to the site's directory or absolute. Files under the
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   staticDirectories: ['static'],
 };
 ```
@@ -501,7 +509,7 @@ An array of tags that will be inserted in the HTML `<head>`. The values must be
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   headTags: [
     {
       tagName: 'link',
@@ -527,7 +535,7 @@ Note that `<script>` added here are render-blocking, so you might want to add `a
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   scripts: [
     // String format.
     'https://docusaurus.io/script.js',
@@ -549,7 +557,7 @@ An array of CSS sources to load. The values can be either strings or plain objec
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   stylesheets: [
     // String format.
     'https://docusaurus.io/style.css',
@@ -574,11 +582,8 @@ An array of [client modules](../advanced/client.mdx#client-modules) to load glob
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
-  clientModules: [
-    require.resolve('./mySiteGlobalJs.js'),
-    require.resolve('./mySiteGlobalCss.css'),
-  ],
+export default {
+  clientModules: ['./mySiteGlobalJs.js', './mySiteGlobalCss.css'],
 };
 ```
 
@@ -591,7 +596,7 @@ An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   ssrTemplate: `<!DOCTYPE html>
 <html <%~ it.htmlAttributes %>>
   <head>
@@ -631,7 +636,7 @@ Will be used as title delimiter in the generated `<title>` tag.
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   titleDelimiter: '🦖', // Defaults to `|`
 };
 ```
@@ -645,7 +650,7 @@ When enabled, will show a banner in case your site can't load its CSS or JavaScr
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   baseUrlIssueBanner: true, // Defaults to `true`
 };
 ```

website/versioned_docs/version-3.0.0-rc.0/api/plugin-methods/README.mdx

@@ -47,7 +47,7 @@ Here's a mental model for a presumptuous plugin implementation.
 // A JavaScript function that returns an object.
 // `context` is provided by Docusaurus. Example: siteConfig can be accessed from context.
 // `opts` is the user-defined options.
-async function myPlugin(context, opts) {
+export default async function myPlugin(context, opts) {
   return {
     // A compulsory field used as the namespace for directories to cache
     // the intermediate data for each plugin.
@@ -132,15 +132,13 @@ async function myPlugin(context, opts) {
   };
 }
 
-myPlugin.validateOptions = ({options, validate}) => {
+export function validateOptions({options, validate}) {
   const validatedOptions = validate(myValidationSchema, options);
   return validatedOptions;
-};
+}
 
-myPlugin.validateThemeConfig = ({themeConfig, validate}) => {
+export function validateThemeConfig({themeConfig, validate}) {
   const validatedThemeConfig = validate(myValidationSchema, options);
   return validatedThemeConfig;
-};
-
-module.exports = myPlugin;
+}
 ```

website/versioned_docs/version-3.0.0-rc.0/api/plugin-methods/extend-infrastructure.mdx

@@ -15,8 +15,9 @@ Use this for files that are consumed server-side, because theme files are automa
 Example:
 
 ```js title="docusaurus-plugin/src/index.js"
-const path = require('path');
-module.exports = function (context, options) {
+import path from 'path';
+
+export default function (context, options) {
   return {
     name: 'docusaurus-plugin',
     // highlight-start
@@ -26,7 +27,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `extendCli(cli)` {#extendCli}
@@ -42,7 +43,7 @@ The commander version matters! We use commander v5, and make sure you are referr
 Example:
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'docusaurus-plugin',
     // highlight-start
@@ -56,7 +57,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `getThemePath()` {#getThemePath}
@@ -66,9 +67,7 @@ Returns the path to the directory where the theme components can be found. When
 For example, your `getThemePath` can be:
 
 ```js title="my-theme/src/index.js"
-const path = require('path');
-
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'my-theme',
     // highlight-start
@@ -77,7 +76,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `getTypeScriptThemePath()` {#getTypeScriptThemePath}
@@ -95,9 +94,7 @@ You should also format these files with Prettier. Remember—JS files can and wi
 Example:
 
 ```js title="my-theme/src/index.js"
-const path = require('path');
-
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'my-theme',
     // highlight-start
@@ -111,7 +108,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `getSwizzleComponentList()` {#getSwizzleComponentList}
@@ -121,15 +118,15 @@ module.exports = function (context, options) {
 Returns a list of stable components that are considered safe for swizzling. These components will be swizzlable without `--danger`. All components are considered unstable by default. If an empty array is returned, all components are considered unstable. If `undefined` is returned, all components are considered stable.
 
 ```js title="my-theme/src/index.js"
-const swizzleAllowedComponents = [
-  'CodeBlock',
-  'DocSidebar',
-  'Footer',
-  'NotFound',
-  'SearchBar',
-  'hooks/useTheme',
-  'prism-include-languages',
-];
-
-myTheme.getSwizzleComponentList = () => swizzleAllowedComponents;
+export function getSwizzleComponentList() {
+  return [
+    'CodeBlock',
+    'DocSidebar',
+    'Footer',
+    'NotFound',
+    'SearchBar',
+    'hooks/useTheme',
+    'prism-include-languages',
+  ];
+}
 ```

website/versioned_docs/version-3.0.0-rc.0/api/plugin-methods/i18n-lifecycles.mdx

@@ -19,8 +19,8 @@ These files will be written by the [`write-translations` CLI](../../cli.mdx#docu
 
 Example:
 
-```js
-module.exports = function (context, options) {
+```js title="my-plugin.js"
+export default function (context, options) {
   return {
     name: 'my-plugin',
     // highlight-start
@@ -40,7 +40,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `translateContent({content,translationFiles})` {#translateContent}
@@ -53,8 +53,8 @@ The `contentLoaded()` lifecycle will be called with the localized plugin content
 
 Example:
 
-```js
-module.exports = function (context, options) {
+```js title="my-plugin.js"
+export default function (context, options) {
   return {
     name: 'my-plugin',
     // highlight-start
@@ -69,7 +69,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `translateThemeConfig({themeConfig,translationFiles})` {#translateThemeConfig}
@@ -80,8 +80,8 @@ Returns the localized `themeConfig`.
 
 Example:
 
-```js
-module.exports = function (context, options) {
+```js title="my-plugin.js"
+export default function (context, options) {
   return {
     name: 'my-theme',
     // highlight-start
@@ -96,7 +96,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `async getDefaultCodeTranslationMessages()` {#getDefaultCodeTranslationMessages}
@@ -107,8 +107,8 @@ It should return messages in `Record<string, string>`, where keys are translatio
 
 Example:
 
-```js
-module.exports = function (context, options) {
+```js title="my-plugin.js"
+export default function (context, options) {
   return {
     name: 'my-theme',
     // highlight-start
@@ -117,5 +117,5 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```

website/versioned_docs/version-3.0.0-rc.0/api/plugin-methods/lifecycle-apis.mdx

@@ -14,7 +14,7 @@ Plugins should use this lifecycle to fetch from data sources (filesystem, remote
 For example, this plugin below returns a random integer between 1 and 10 as content.
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'docusaurus-plugin',
     // highlight-start
@@ -23,7 +23,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `async contentLoaded({content, actions})` {#contentLoaded}
@@ -183,7 +183,7 @@ You may use them to return your webpack configuration conditionally.
 For example, this plugin below modify the webpack config to transpile `.foo` files.
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'custom-docusaurus-plugin',
     // highlight-start
@@ -202,7 +202,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ### `content` {#content-1}
@@ -216,7 +216,7 @@ We merge the Webpack configuration parts of plugins into the global Webpack conf
 It is possible to specify the merge strategy. For example, if you want a webpack rule to be prepended instead of appended:
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'custom-docusaurus-plugin',
     configureWebpack(config, isServer, utils) {
@@ -228,7 +228,7 @@ module.exports = function (context, options) {
       };
     },
   };
-};
+}
 ```
 
 Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge#merging-with-strategies) for more details.
@@ -238,7 +238,7 @@ Read the [webpack-merge strategy doc](https://github.com/survivejs/webpack-merge
 The dev server can be configured through returning a `devServer` field.
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'custom-docusaurus-plugin',
     configureWebpack(config, isServer, utils) {
@@ -251,7 +251,7 @@ module.exports = function (context, options) {
       };
     },
   };
-};
+}
 ```
 
 ## `configurePostCss(options)` {#configurePostCss}
@@ -272,7 +272,7 @@ const postcssOptions = {
 Example:
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'docusaurus-plugin',
     // highlight-start
@@ -283,7 +283,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `postBuild(props)` {#postBuild}
@@ -309,7 +309,7 @@ interface Props {
 Example:
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'docusaurus-plugin',
     // highlight-start
@@ -321,7 +321,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 ## `injectHtmlTags({content})` {#injectHtmlTags}
@@ -361,7 +361,7 @@ type HtmlTagObject = {
 Example:
 
 ```js title="docusaurus-plugin/src/index.js"
-module.exports = function (context, options) {
+export default function (context, options) {
   return {
     name: 'docusaurus-plugin',
     loadContent: async () => {
@@ -394,7 +394,7 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```
 
 Tags will be added as follows:
@@ -410,9 +410,7 @@ Returns an array of paths to the [client modules](../../advanced/client.mdx#clie
 As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:
 
 ```js title="my-theme/src/index.js"
-const path = require('path');
-
-module.exports = function (context, options) {
+export default function (context, options) {
   const {customCss, customJs} = options || {};
   return {
     name: 'name-of-my-theme',
@@ -422,5 +420,5 @@ module.exports = function (context, options) {
     },
     // highlight-end
   };
-};
+}
 ```

website/versioned_docs/version-3.0.0-rc.0/api/plugin-methods/static-methods.mdx

@@ -22,34 +22,14 @@ Returns validated and normalized options for the plugin. This method is called b
 
 [Joi](https://www.npmjs.com/package/joi) is recommended for validation and normalization of options.
 
-To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-validation")`
+To avoid mixing Joi versions, use `import {Joi} from '@docusaurus/utils-validation'`
 
 :::
 
 If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options and return options in case of success.
 
 ```js title="my-plugin/src/index.js"
-function myPlugin(context, options) {
-  return {
-    name: 'docusaurus-plugin',
-    // rest of methods
-  };
-}
-
-// highlight-start
-myPlugin.validateOptions = ({options, validate}) => {
-  const validatedOptions = validate(myValidationSchema, options);
-  return validatedOptions;
-};
-// highlight-end
-
-module.exports = myPlugin;
-```
-
-In TypeScript, you can also choose to export this as a separate named export.
-
-```ts title="my-plugin/src/index.ts"
-export default function (context, options) {
+export default function myPlugin(context, options) {
   return {
     name: 'docusaurus-plugin',
     // rest of methods
@@ -80,34 +60,14 @@ Return validated and normalized configuration for the theme.
 
 [Joi](https://www.npmjs.com/package/joi) is recommended for validation and normalization of theme config.
 
-To avoid mixing Joi versions, use `const {Joi} = require("@docusaurus/utils-validation")`
+To avoid mixing Joi versions, use `import {Joi} from '@docusaurus/utils-validation'`
 
 :::
 
 If you don't use **[Joi](https://www.npmjs.com/package/joi)** for validation you can throw an Error in case of invalid options.
 
 ```js title="my-theme/src/index.js"
-function myPlugin(context, options) {
-  return {
-    name: 'docusaurus-plugin',
-    // rest of methods
-  };
-}
-
-// highlight-start
-myPlugin.validateThemeConfig = ({themeConfig, validate}) => {
-  const validatedThemeConfig = validate(myValidationSchema, options);
-  return validatedThemeConfig;
-};
-// highlight-end
-
-module.exports = validateThemeConfig;
-```
-
-In TypeScript, you can also choose to export this as a separate named export.
-
-```ts title="my-theme/src/index.ts"
-export default function (context, options) {
+export default function myPlugin(context, options) {
   return {
     name: 'docusaurus-plugin',
     // rest of methods

website/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-client-redirects.mdx

@@ -89,7 +89,7 @@ type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;
 Here's an example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-client-redirects',

website/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-content-blog.mdx

@@ -169,7 +169,7 @@ const config = {
   blogPostComponent: '@theme/BlogPostPage',
   blogTagsListComponent: '@theme/BlogTagsListPage',
   blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
-  remarkPlugins: [require('remark-math')],
+  remarkPlugins: [require('./my-remark-plugin')],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],
@@ -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/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-content-docs.mdx

@@ -234,7 +234,7 @@ const config = {
   },
   docLayoutComponent: '@theme/DocPage',
   docItemComponent: '@theme/DocItem',
-  remarkPlugins: [require('remark-math')],
+  remarkPlugins: [require('./my-remark-plugin')],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],

website/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-content-pages.mdx

@@ -72,7 +72,7 @@ const config = {
     '**/__tests__/**',
   ],
   mdxPageComponent: '@theme/MDXPage',
-  remarkPlugins: [require('remark-math')],
+  remarkPlugins: [require('./my-remark-plugin')],
   rehypePlugins: [],
   beforeDefaultRemarkPlugins: [],
   beforeDefaultRehypePlugins: [],

website/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-debug.mdx

@@ -21,7 +21,7 @@ If you use the plugin via the classic preset, the preset will **enable the plugi
 If you use a standalone plugin, you may need to achieve the same effect by checking the environment:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     // highlight-next-line
     process.env.NODE_ENV === 'production' && '@docusaurus/plugin-debug',
@@ -75,7 +75,7 @@ Most Docusaurus users configure this plugin through the preset options.
 If you use a preset, configure this plugin through the [preset options](../../using-plugins.mdx#docusauruspreset-classic):
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -96,7 +96,7 @@ module.exports = {
 If you are using a standalone plugin, provide options directly to the plugin:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // highlight-next-line
   plugins: ['@docusaurus/plugin-debug'],
 };

website/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-ideal-image.mdx

@@ -73,7 +73,7 @@ Accepted fields:
 Here's an example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-ideal-image',

website/versioned_docs/version-3.0.0-rc.0/api/plugins/plugin-pwa.mdx

@@ -20,7 +20,7 @@ Create a [PWA manifest](https://web.dev/add-manifest/) at `./static/manifest.jso
 Modify `docusaurus.config.js` with a minimal PWA config, like:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-pwa',
@@ -148,7 +148,7 @@ The [`standalone` strategy](https://petelepage.com/blog/2019/07/is-my-pwa-instal
 - Default: `{}`
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-pwa',
@@ -179,7 +179,7 @@ module.exports = {
 Array of objects containing `tagName` and key-value pairs for attributes to inject into the `<head>` tag. Technically you can inject any head tag through this, but it's ideally used for tags to make your site PWA compliant. Here's a list of tag to make your app fully compliant:
 
 ```js
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-pwa',
@@ -288,7 +288,7 @@ The Docusaurus site manifest can serve as an inspiration:
 import CodeBlock from '@theme/CodeBlock';
 
 <CodeBlock className="language-json">
-  {JSON.stringify(require("@site/static/manifest.json"),null,2)}
+  {JSON.stringify(require('@site/static/manifest.json'),null,2)}
 </CodeBlock>
 ```
 

website/versioned_docs/version-3.0.0-rc.0/api/themes/theme-classic.mdx

@@ -58,6 +58,6 @@ Most Docusaurus users configure this plugin through the preset options.
 // Plugin Options: @docusaurus/theme-classic
 
 const config = {
-  customCss: require.resolve('./src/css/custom.css'),
+  customCss: './src/css/custom.css',
 };
 ```

website/versioned_docs/version-3.0.0-rc.0/api/themes/theme-configuration.mdx

@@ -38,7 +38,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-start
     colorMode: {
@@ -80,7 +80,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-next-line
     image: 'img/docusaurus.png',
@@ -109,7 +109,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-next-line
     metadata: [{name: 'twitter:card', content: 'summary'}],
@@ -142,7 +142,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-start
     announcementBar: {
@@ -209,7 +209,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       title: 'Site Title',
@@ -236,7 +236,7 @@ module.exports = {
 You can add items to the navbar via `themeConfig.navbar.items`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       // highlight-start
@@ -311,7 +311,7 @@ In addition to the fields above, you can specify other arbitrary attributes that
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -368,7 +368,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -422,7 +422,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -471,7 +471,7 @@ Use this navbar item type if your sidebar is updated often and the order is not
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -490,7 +490,7 @@ module.exports = {
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorial: [
     {
       type: 'autogenerated',
@@ -537,7 +537,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -580,7 +580,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -625,7 +625,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -668,7 +668,7 @@ However, with this special navbar item type, you can change the default location
 ```
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -704,7 +704,7 @@ You can also render your own HTML markup inside a navbar item using this navbar
 ```
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -726,7 +726,7 @@ module.exports = {
 You can enable this cool UI feature that automatically hides the navbar when a user starts scrolling down the page, and show it again when the user scrolls up.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       // highlight-next-line
@@ -743,7 +743,7 @@ You can set the static Navbar style without disabling the theme switching abilit
 Currently, there are two possible style options: `dark` and `primary` (based on the `--ifm-color-primary` color). You can see the styles preview in the [Infima documentation](https://infima.dev/docs/components/navbar/).
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       // highlight-next-line
@@ -799,12 +799,14 @@ By default, we use [Palenight](https://github.com/FormidableLabs/prism-react-ren
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+import {themes as prismThemes} from 'prism-react-renderer';
+
+export default {
   themeConfig: {
     prism: {
       // highlight-start
-      theme: require('prism-react-renderer/themes/github'),
-      darkTheme: require('prism-react-renderer/themes/dracula'),
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
       // highlight-end
     },
   },
@@ -824,7 +826,7 @@ You can set a default language for code blocks if no language is added after the
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     prism: {
       // highlight-next-line
@@ -858,7 +860,7 @@ Accepted fields:
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-start
     footer: {
@@ -915,7 +917,7 @@ Accepted fields of each `FooterItem`:
 Example multi-column configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   footer: {
     // highlight-start
     links: [
@@ -967,7 +969,7 @@ A simple footer just has a list of `FooterItem`s displayed in a row.
 Example simple configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   footer: {
     // highlight-start
     links: [
@@ -1016,7 +1018,7 @@ You can adjust the default table of contents via `themeConfig.tableOfContents`.
 Example configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-start
     tableOfContents: {

website/versioned_docs/version-3.0.0-rc.0/api/themes/theme-live-codeblock.mdx

@@ -14,7 +14,7 @@ npm install --save @docusaurus/theme-live-codeblock
 ### Configuration {#configuration}
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: ['@docusaurus/theme-live-codeblock'],
   themeConfig: {
     liveCodeBlock: {

website/versioned_docs/version-3.0.0-rc.0/api/themes/theme-mermaid.mdx

@@ -14,7 +14,7 @@ npm install --save @docusaurus/theme-mermaid
 ## Configuration {#configuration}
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themes: ['@docusaurus/theme-mermaid'],
   // In order for Mermaid code blocks in Markdown to work,
   // you also need to enable the Remark plugin with this option

website/versioned_docs/version-3.0.0-rc.0/blog.mdx

@@ -22,7 +22,7 @@ To set up your site's blog, start by creating a `blog` directory.
 Then, add an item link to your blog within `docusaurus.config.js`:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // ...
     navbar: {
@@ -40,12 +40,12 @@ module.exports = {
 
 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
@@ -108,7 +108,7 @@ But anything from here on down will not be.
 By default, 10 posts are shown on each blog list page, but you can control pagination with the `postsPerPage` option in the plugin configuration. If you set `postsPerPage: 'ALL'`, pagination will be disabled and all posts will be displayed on the first page. You can also add a meta description to the blog list page for better SEO:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [
@@ -134,7 +134,7 @@ The blog sidebar displays recent blog posts. The default number of items shown i
 You can also alter the sidebar heading text with the `blogSidebarTitle` option. For example, if you have set `blogSidebarCount: 'ALL'`, instead of the default "Recent posts", you may rather make it say "All posts":
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -385,7 +385,7 @@ An author, either declared through front matter or through the authors map, need
 Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -419,7 +419,7 @@ Use the callback for all your customization needs:
 **Disable reading time on one page:**
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -457,7 +457,7 @@ This page will no longer display the reading time stats!
 **Pass options to the default reading time function:**
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -482,9 +482,9 @@ module.exports = {
 **Use a custom implementation of reading time:**
 
 ```js title="docusaurus.config.js"
-const myReadingTime = require('./myReadingTime');
+import myReadingTime from './myReadingTime';
 
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -539,7 +539,7 @@ type BlogOptions = {
 Example usage:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [
@@ -597,10 +597,10 @@ 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"
-module.exports = {
+export default {
   // ...
   presets: [
     [
@@ -640,7 +640,7 @@ Set the `routeBasePath` to the URL route that you want your second blog to be ac
 As documented for [multi-instance plugins](./using-plugins.mdx#multi-instance-plugins-and-plugin-ids), you need to assign a unique ID to the plugins.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: [
     [

website/versioned_docs/version-3.0.0-rc.0/configuration.mdx

@@ -25,15 +25,28 @@ The `docusaurus.config.js` file is run in Node.js and should export either:
 
 :::info
 
-The `docusaurus.config.js` file only supports the [**CommonJS**](https://flaviocopes.com/commonjs/) module system:
+The `docusaurus.config.js` file supports:
 
-- **Required:** use `module.exports = /* your config*/` to export your Docusaurus config
-- **Optional:** use `require("lib")` to import Node.js packages
-- **Optional:** use `await import("lib")` (dynamic import) in an async function to import ESM-Only Node.js packages
+- [**ES Modules**](https://flaviocopes.com/es-modules/)
+- [**CommonJS**](https://flaviocopes.com/commonjs/)
+- [**TypeScript**](./typescript-support.mdx#typing-config)
+
+Constraints:
+
+- **Required:** use `export default /* your config*/` (or `module.exports` to export your Docusaurus config
+- **Optional:** use `import Lib from 'lib'` (or `require('lib')`) to import Node.js packages
 
 :::
 
-Node.js gives us the ability to declare our Docusaurus configuration in various **equivalent ways**, and all the following config examples lead to the exact same result:
+Docusaurus gives us the ability to declare its configuration in various **equivalent ways**, and all the following config examples lead to the exact same result:
+
+```js title="docusaurus.config.js"
+export default {
+  title: 'Docusaurus',
+  url: 'https://docusaurus.io',
+  // your site config ...
+};
+```
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -43,6 +56,16 @@ module.exports = {
 };
 ```
 
+```ts title="docusaurus.config.ts"
+import type {Config} from '@docusaurus/types';
+
+export default {
+  title: 'Docusaurus',
+  url: 'https://docusaurus.io',
+  // your site config ...
+} satisfies Config;
+```
+
 ```js title="docusaurus.config.js"
 const config = {
   title: 'Docusaurus',
@@ -50,27 +73,27 @@ const config = {
   // your site config ...
 };
 
-module.exports = config;
+export default config;
 ```
 
 ```js title="docusaurus.config.js"
-module.exports = function configCreator() {
+export default function configCreator() {
   return {
     title: 'Docusaurus',
     url: 'https://docusaurus.io',
     // your site config ...
   };
-};
+}
 ```
 
 ```js title="docusaurus.config.js"
-module.exports = async function createConfigAsync() {
+export default async function createConfigAsync() {
   return {
     title: 'Docusaurus',
     url: 'https://docusaurus.io',
     // your site config ...
   };
-};
+}
 ```
 
 :::tip Using ESM-only packages
@@ -78,7 +101,7 @@ module.exports = async function createConfigAsync() {
 Using an async config creator can be useful to import ESM-only modules (notably most Remark plugins). It is possible to import such modules thanks to dynamic imports:
 
 ```js title="docusaurus.config.js"
-module.exports = async function createConfigAsync() {
+export default async function createConfigAsync() {
   // Use a dynamic import instead of require('esm-lib')
   // highlight-next-line
   const lib = await import('lib');
@@ -88,7 +111,7 @@ module.exports = async function createConfigAsync() {
     url: 'https://docusaurus.io',
     // rest of your site config...
   };
-};
+}
 ```
 
 :::
@@ -120,7 +143,7 @@ It is recommended to check the [deployment docs](deployment.mdx) for more inform
 List the [themes](./using-plugins.mdx#using-themes), [plugins](./using-plugins.mdx), and [presets](./using-plugins.mdx#using-presets) for your site in the `themes`, `plugins`, and `presets` fields, respectively. These are typically npm packages:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: [
     '@docusaurus/plugin-content-blog',
@@ -135,7 +158,7 @@ module.exports = {
 Docusaurus supports [**module shorthands**](./using-plugins.mdx#module-shorthands), allowing you to simplify the above configuration as:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: ['content-blog', 'content-pages'],
   themes: ['classic'],
@@ -147,9 +170,9 @@ module.exports = {
 They can also be loaded from local directories:
 
 ```js title="docusaurus.config.js"
-const path = require('path');
+import path from 'path';
 
-module.exports = {
+export default {
   // ...
   themes: [path.resolve(__dirname, '/path/to/docusaurus-local-theme')],
 };
@@ -158,7 +181,7 @@ module.exports = {
 To specify options for a plugin or theme, replace the name of the plugin or theme in the config file with an array containing the name and an options object:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: [
     [
@@ -178,17 +201,17 @@ module.exports = {
 To specify options for a plugin or theme that is bundled in a preset, pass the options through the `presets` field. In this example, `docs` refers to `@docusaurus/plugin-content-docs` and `theme` refers to `@docusaurus/theme-classic`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [
       '@docusaurus/preset-classic',
       {
         docs: {
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: './sidebars.js',
         },
         theme: {
-          customCss: [require.resolve('./src/css/custom.css')],
+          customCss: ['./src/css/custom.css'],
         },
       },
     ],
@@ -211,7 +234,7 @@ Docusaurus guards `docusaurus.config.js` from unknown fields. To add custom fiel
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-start
   customFields: {
@@ -255,8 +278,8 @@ If you just want to use those fields on the client side, you could create your o
 For new Docusaurus projects, we automatically generated a `babel.config.js` in the project root.
 
 ```js title="babel.config.js"
-module.exports = {
-  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+export default {
+  presets: ['@docusaurus/core/lib/babel/preset'],
 };
 ```
 

website/versioned_docs/version-3.0.0-rc.0/deployment.mdx

@@ -61,9 +61,9 @@ Putting potentially sensitive information in the environment is common practice.
 
 ```js title="docusaurus.config.js"
 // If you are using dotenv (https://www.npmjs.com/package/dotenv)
-require('dotenv').config();
+import 'dotenv/config';
 
-module.exports = {
+export default {
   title: '...',
   url: process.env.URL, // You can use environment variables to control site specifics as well
   // highlight-start
@@ -154,10 +154,10 @@ 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"
-module.exports = {
+export default {
   // highlight-start
   url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
   baseUrl: '/', // Base directory of your site relative to your repo
@@ -263,7 +263,7 @@ GitHub Pages adds a trailing slash to Docusaurus URLs by default. It is recommen
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   url: 'https://endiliey.github.io', // Your website URL
   baseUrl: '/',

website/versioned_docs/version-3.0.0-rc.0/docusaurus-core.mdx

@@ -32,7 +32,7 @@ const SafeComponent = () => (
 ```
 
 ```mdx-code-block
-import ErrorBoundaryTestButton from "@site/src/components/ErrorBoundaryTestButton"
+import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton'
 ```
 
 :::tip

website/versioned_docs/version-3.0.0-rc.0/guides/docs/docs-introduction.mdx

@@ -44,7 +44,7 @@ All docs will be served under the subroute `docs/`. But what if **your site only
 Assume that you have the following in your configuration:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [
@@ -66,7 +66,7 @@ module.exports = {
 To enter docs-only mode, change it to like this:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [
@@ -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/versioned_docs/version-3.0.0-rc.0/guides/docs/docs-multi-instance.mdx

@@ -64,7 +64,7 @@ In this case, you should use the same plugin twice in your site configuration.
 When using the preset:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -75,7 +75,7 @@ module.exports = {
           // highlight-end
           path: 'product',
           routeBasePath: 'product',
-          sidebarPath: require.resolve('./sidebarsProduct.js'),
+          sidebarPath: './sidebarsProduct.js',
           // ... other options
         },
       },
@@ -90,7 +90,7 @@ module.exports = {
         // highlight-end
         path: 'community',
         routeBasePath: 'community',
-        sidebarPath: require.resolve('./sidebarsCommunity.js'),
+        sidebarPath: './sidebarsCommunity.js',
         // ... other options
       },
     ],
@@ -101,7 +101,7 @@ module.exports = {
 When not using the preset:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-content-docs',
@@ -111,7 +111,7 @@ module.exports = {
         // highlight-end
         path: 'product',
         routeBasePath: 'product',
-        sidebarPath: require.resolve('./sidebarsProduct.js'),
+        sidebarPath: './sidebarsProduct.js',
         // ... other options
       },
     ],
@@ -123,7 +123,7 @@ module.exports = {
         // highlight-end
         path: 'community',
         routeBasePath: 'community',
-        sidebarPath: require.resolve('./sidebarsCommunity.js'),
+        sidebarPath: './sidebarsCommunity.js',
         // ... other options
       },
     ],
@@ -190,7 +190,7 @@ Each docs-related [theme navbar items](../../api/themes/theme-configuration.mdx#
 For example, if you want to have one version dropdown for each mobile SDK (iOS and Android), you could do:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [

website/versioned_docs/version-3.0.0-rc.0/guides/docs/sidebar/autogenerated.mdx

@@ -21,7 +21,7 @@ type SidebarItemAutogenerated = {
 Docusaurus can generate a full sidebar from your docs folder:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   myAutogeneratedSidebar: [
     // highlight-start
     {
@@ -67,7 +67,7 @@ docs
 And assume every doc's ID is just its file name. If you define an autogenerated sidebar like this:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     'intro',
     {
@@ -109,7 +109,7 @@ module.exports = {
 It would be resolved as:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     'intro',
     {
@@ -175,7 +175,7 @@ A category index document is a document following one of those filename conventi
 This is equivalent to using a category with a [doc link](items.mdx#category-doc-link):
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: [
     // highlight-start
     {
@@ -215,7 +215,7 @@ some-doc
 It is possible to opt out any of the category index conventions, or define even more conventions. You can inject your own `isCategoryIndex` matcher through the [`sidebarItemsGenerator`](#customize-the-sidebar-items-generator) callback. For example, you can also pick `intro` as another file name eligible for automatically becoming the category index.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-content-docs',
@@ -247,7 +247,7 @@ module.exports = {
 Or choose to not have any category index convention.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-content-docs',
@@ -426,7 +426,7 @@ Updating a number prefix can be annoying, as it can require **updating multiple
 You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-content-docs',
@@ -477,7 +477,7 @@ function reverseSidebarItems(items) {
 }
 // highlight-end
 
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-content-docs',

website/versioned_docs/version-3.0.0-rc.0/guides/docs/sidebar/index.mdx

@@ -16,14 +16,14 @@ To use sidebars on your Docusaurus site:
 2. Pass this object into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
       {
         docs: {
           // highlight-next-line
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: './sidebars.js',
         },
       },
     ],
@@ -44,7 +44,7 @@ import DocCardList from '@theme/DocCardList';
 If the `sidebarPath` is unspecified, Docusaurus [automatically generates a sidebar](autogenerated.mdx) for you, by using the filesystem structure of the `docs` folder:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     {
       type: 'autogenerated',
@@ -71,7 +71,7 @@ type Sidebar =
 For example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     {
       type: 'category',
@@ -123,7 +123,7 @@ type SidebarsFile = {
 By enabling the `themeConfig.docs.sidebar.hideable` option, you can make the entire sidebar hideable, allowing users to better focus on the content. This is especially useful when content is consumed on medium-sized screens (e.g. tablets).
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-start
     docs: {
@@ -141,7 +141,7 @@ module.exports = {
 The `themeConfig.docs.sidebar.autoCollapseCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // highlight-start
     docs: {
@@ -178,7 +178,7 @@ By default, breadcrumbs are rendered at the top, using the "sidebar path" of the
 This behavior can be disabled with plugin options:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',

website/versioned_docs/version-3.0.0-rc.0/guides/docs/sidebar/items.mdx

@@ -42,7 +42,7 @@ type SidebarItemDoc =
 Example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     // Normal syntax:
     // highlight-start
@@ -92,7 +92,7 @@ type SidebarItemLink = {
 Example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   myLinksSidebar: [
     // highlight-start
     // External link
@@ -133,7 +133,7 @@ type SidebarItemHtml = {
 Example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   myHtmlSidebar: [
     // highlight-start
     {
@@ -151,7 +151,7 @@ module.exports = {
 The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   myHtmlSidebar: [
     {
       type: 'html',
@@ -186,7 +186,7 @@ type SidebarItemCategory = {
 Example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: [
     {
       type: 'category',
@@ -211,7 +211,7 @@ module.exports = {
 Use the [**shorthand syntax**](#category-shorthand) when you don't need customizations:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: {
     Guides: [
       'creating-pages',
@@ -242,7 +242,7 @@ Autogenerated categories can use the [`_category_.yml`](./autogenerated.mdx#cate
 You can auto-generate an index page that displays all the direct children of this category. The `slug` allows you to customize the generated page's route, which defaults to `/category/[categoryName]`.
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: [
     {
       type: 'category',
@@ -276,7 +276,7 @@ Use `generated-index` links as a quick way to get an introductory document.
 A category can link to an existing document.
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: [
     {
       type: 'category',
@@ -317,7 +317,7 @@ import DocCardList from '@theme/DocCardList';
 We support the option to expand/collapse categories. Categories are collapsible by default, but you can disable collapsing with `collapsible: false`.
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: [
     {
       type: 'category',
@@ -340,7 +340,7 @@ module.exports = {
 To make all categories non-collapsible by default, set the `sidebarCollapsible` option in `plugin-content-docs` to `false`:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -366,7 +366,7 @@ The option in `sidebars.js` takes precedence over plugin configuration, so it is
 Collapsible categories are collapsed by default. If you want them to be expanded on the first render, you can set `collapsed` to `false`:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   docs: {
     Guides: [
       'creating-pages',
@@ -385,7 +385,7 @@ module.exports = {
 Similar to `collapsible`, you can also set the global configuration `options.sidebarCollapsed` to `false`. Individual `collapsed` options in `sidebars.js` will still take precedence over this configuration.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -420,7 +420,7 @@ An item with type `doc` can be simply a string representing its ID:
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   sidebar: [
     // highlight-start
     {
@@ -438,7 +438,7 @@ module.exports = {
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   sidebar: [
     // highlight-start
     'myDoc',
@@ -455,7 +455,7 @@ module.exports = {
 So it's possible to simplify the example above to:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     {
       type: 'category',
@@ -494,7 +494,7 @@ A category item can be represented by an object whose key is its label, and the
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   sidebar: [
     // highlight-start
     {
@@ -513,7 +513,7 @@ module.exports = {
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   sidebar: [
     // highlight-start
     {
@@ -532,7 +532,7 @@ module.exports = {
 This permits us to simplify that example to:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     // highlight-start
     {
@@ -554,7 +554,7 @@ module.exports = {
 Each shorthand object after this transformation will contain exactly one entry. Now consider the further simplified example below:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   mySidebar: [
     // highlight-start
     {
@@ -581,7 +581,7 @@ Wherever you have an array of items that is reduced to one category shorthand, y
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   sidebar: [
     {
       'Getting started': ['doc1'],
@@ -602,7 +602,7 @@ module.exports = {
 ```
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   sidebar: {
     'Getting started': ['doc1'],
     Docusaurus: {

website/versioned_docs/version-3.0.0-rc.0/guides/docs/sidebar/multiple-sidebars.mdx

@@ -18,7 +18,7 @@ The Docusaurus site is a good example of using multiple sidebars:
 Consider this example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorialSidebar: {
     'Category A': ['doc1', 'doc2'],
   },
@@ -33,7 +33,7 @@ When browsing `doc1` or `doc2`, the `tutorialSidebar` will be displayed; when br
 Following the example above, if a `commonDoc` is included in both sidebars:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorialSidebar: {
     'Category A': ['doc1', 'doc2', 'commonDoc'],
   },
@@ -51,7 +51,7 @@ When you add doc Y to sidebar X, it creates a two-way binding: sidebar X contain
 Front matter option `displayed_sidebar` will forcibly set the sidebar association. For the same example, you can still use doc shorthands without any special configuration:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorialSidebar: {
     'Category A': ['doc1', 'doc2'],
   },
@@ -88,7 +88,7 @@ If a sidebar is displayed by setting `displayed_sidebar` front matter, and this
 You can customize pagination with front matter `pagination_next` and `pagination_prev`. Consider this sidebar:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorial: [
     'introduction',
     {
@@ -123,7 +123,7 @@ It is particularly useful where you wish to link to the same document from multi
 Consider this example:
 
 ```js title="sidebars.js"
-module.exports = {
+export default {
   tutorialSidebar: {
     'Category A': [
       'doc1',
@@ -135,7 +135,6 @@ module.exports = {
   },
   apiSidebar: ['doc3', 'doc4', 'commonDoc'],
 };
-}
 ```
 
 You can think of the `ref` type as the equivalent to doing the following:

website/versioned_docs/version-3.0.0-rc.0/guides/docs/versioning.mdx

@@ -187,7 +187,7 @@ Docusaurus defaults work great for the first use case. We will label the current
 **For the 2nd use case**: if you release v1 and don't plan to work on v2 anytime soon, instead of versioning v1 and having to maintain the docs in 2 folders (`./docs` + `./versioned_docs/version-1.0.0`), you may consider "pretending" that the current version is a cut version by giving it a path and a label:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     '@docusaurus/preset-classic',
     docs: {

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-admonitions.mdx

@@ -275,7 +275,7 @@ export default function AdmonitionWrapper(props) {
 Admonitions are implemented with a [Remark plugin](./markdown-features-plugins.mdx). The plugin is designed to be configurable. To customize the Remark plugin for a specific content plugin (docs, blog, pages), pass the options through the `admonitions` key.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -306,7 +306,7 @@ By default, the theme doesn't know what do to with custom admonition keywords su
 If you registered a new admonition type `my-custom-admonition` via the following config:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -64,11 +64,13 @@ By default, the Prism [syntax highlighting theme](https://github.com/FormidableL
 For example, if you prefer to use the `dracula` highlighting theme:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+import {themes as prismThemes} from 'prism-react-renderer';
+
+export default {
   themeConfig: {
     prism: {
       // highlight-next-line
-      theme: require('prism-react-renderer/themes/dracula'),
+      theme: prismThemes.dracula,
     },
   },
 };
@@ -97,7 +99,7 @@ Each additional language has to be a valid Prism component name. For example, Pr
 For example, if you want to add highlighting for the PowerShell language:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   themeConfig: {
     prism: {
@@ -299,7 +301,7 @@ You can declare custom magic comments through theme config. For example, you can
 ```
 
 ```js
-module.exports = {
+export default {
   themeConfig: {
     prism: {
       magicComments: [
@@ -443,7 +445,7 @@ npm install --save @docusaurus/theme-live-codeblock
 You will also need to add the plugin to your `docusaurus.config.js`.
 
 ```js {3}
-module.exports = {
+export default {
   // ...
   themes: ['@docusaurus/theme-live-codeblock'],
   // ...
@@ -756,7 +758,7 @@ npm install @docusaurus/remark-plugin-npm2yarn
 Docusaurus provides such a utility out of the box, freeing you from using the `Tabs` component every time. To enable this feature, first install the `@docusaurus/remark-plugin-npm2yarn` package as above, and then in `docusaurus.config.js`, for the plugins where you need this feature (doc, blog, pages, etc.), register it in the `remarkPlugins` option. (See [Docs configuration](../../api/plugins/plugin-content-docs.mdx#ex-config) for more details on configuration format)
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-diagrams.mdx

@@ -18,7 +18,7 @@ npm install --save @docusaurus/theme-mermaid
 Enable Mermaid functionality by adding plugin `@docusaurus/theme-mermaid` and setting `markdown.mermaid` to `true` in your `docusaurus.config.js`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   markdown: {
     mermaid: true,
   },
@@ -55,7 +55,7 @@ See the [Mermaid syntax documentation](https://mermaid-js.github.io/mermaid/#/./
 The diagram dark and light themes can be changed by setting `mermaid.theme` values in the `themeConfig` in your `docusaurus.config.js`. You can set themes for both light and dark mode.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     mermaid: {
       theme: {light: 'neutral', dark: 'forest'},
@@ -71,7 +71,7 @@ See the [Mermaid theme documentation](https://mermaid-js.github.io/mermaid/#/the
 Options in `mermaid.options` will be passed directly to `mermaid.initialize`:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     mermaid: {
       options: {

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-math-equations.mdx

@@ -63,24 +63,62 @@ Make sure to use `remark-math >= 5` and `rehype-katex >= 6` for Docusaurus v3 (u
 
 :::
 
-Those 2 plugins are now only available as ESM packages, and you will need to import them dynamically.
+Those 2 plugins are now [**only available as ES Modules**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c). To simplify usage, it is recommended to use an [**ES Modules**](https://flaviocopes.com/es-modules/) config file:
 
-First, turn your site config into an async config creator function:
+```js title="ES module docusaurus.config.js"
+// highlight-start
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+// highlight-end
 
-```js title="docusaurus.config.js"
+// highlight-start
+export default {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          path: 'docs',
+          // highlight-start
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
+          // highlight-end
+        },
+      },
+    ],
+  ],
+};
+```
+
+<details>
+    <summary>Using a [**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules) config file?</summary>
+
+    If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function:
+
+```js title="CommonJS module docusaurus.config.js"
+// highlight-start
 module.exports = async function createConfigAsync() {
+  // highlight-end
   return {
-    // your site config...
+    presets: [
+      [
+        '@docusaurus/preset-classic',
+        {
+          docs: {
+            path: 'docs',
+            // highlight-start
+            remarkPlugins: [(await import('remark-math')).default],
+            rehypePlugins: [(await import('rehype-katex')).default],
+            // highlight-end
+          },
+        },
+      ],
+    ],
   };
 };
 ```
 
-It is now possible to import the plugins dynamically and add them to your content plugin or preset options (usually `@docusaurus/preset-classic` docs options):
-
-```js
-remarkPlugins: [(await import('remark-math')).default],
-rehypePlugins: [(await import('rehype-katex')).default],
-```
+</details>
 
 Include the KaTeX CSS in your config under `stylesheets`:
 
@@ -99,36 +137,39 @@ stylesheets: [
 Overall the changes look like:
 
 ```js title="docusaurus.config.js"
-module.exports = async function createConfigAsync() {
-  return {
-    title: 'Docusaurus',
-    tagline: 'Build optimized websites quickly, focus on your content',
-    presets: [
-      [
-        '@docusaurus/preset-classic',
-        {
-          docs: {
-            path: 'docs',
-            // highlight-start
-            remarkPlugins: [(await import('remark-math')).default],
-            rehypePlugins: [(await import('rehype-katex')).default],
-            // highlight-end
-          },
-        },
-      ],
-    ],
-    // highlight-start
-    stylesheets: [
+// highlight-start
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+// highlight-end
+
+export default {
+  title: 'Docusaurus',
+  tagline: 'Build optimized websites quickly, focus on your content',
+  presets: [
+    [
+      '@docusaurus/preset-classic',
       {
-        href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
-        type: 'text/css',
-        integrity:
-          'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
-        crossorigin: 'anonymous',
+        docs: {
+          path: 'docs',
+          // highlight-start
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
+          // highlight-end
+        },
       },
     ],
-    // highlight-end
-  };
+  ],
+  // highlight-start
+  stylesheets: [
+    {
+      href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
+      type: 'text/css',
+      integrity:
+        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
+      crossorigin: 'anonymous',
+    },
+  ],
+  // highlight-end
 };
 ```
 
@@ -137,7 +178,7 @@ module.exports = async function createConfigAsync() {
 Loading stylesheets, fonts, and JavaScript libraries from CDN sources is a good practice for popular libraries and assets, since it reduces the amount of assets you have to host. In case you prefer to self-host the `katex.min.css` (along with required KaTeX fonts), you can download the latest version from [KaTeX GitHub releases](https://github.com/KaTeX/KaTeX/releases), extract and copy `katex.min.css` and `fonts` directory (only `.woff2` font types should be enough) to your site's `static` directory, and in `docusaurus.config.js`, replace the stylesheet's `href` from the CDN URL to your local path (say, `/katex/katex.min.css`).
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   stylesheets: [
     {
       href: '/katex/katex.min.css',

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-plugins.mdx

@@ -59,11 +59,41 @@ Next, the `rehype-katex` operates on the Hypertext AST where everything has been
 
 :::warning
 
-Many official Remark/Rehype plugins are using ES Modules, a new JavaScript module system, which Docusaurus doesn't support yet. To work around this issue, we recommend to use dynamic `import()` inside an `async` config creation function.
+Many official Remark/Rehype plugins are [**ES Modules only**](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c), a JavaScript module system, which Docusaurus supports. We recommend using an [**ES Modules**](https://flaviocopes.com/es-modules/) config file to make it easier to import such packages.
 
 :::
 
-Next, add them to the plugin options through plugin or preset config in `docusaurus.config.js`, using dynamic `import()`:
+Next, import your plugins and add them to the plugin options through plugin or preset config in `docusaurus.config.js`:
+
+```js title="docusaurus.config.js"
+// highlight-start
+import remarkMath from 'remark-math';
+import rehypeKatex from 'rehype-katex';
+// highlight-end
+
+// highlight-start
+export default {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          path: 'docs',
+          // highlight-start
+          remarkPlugins: [remarkMath],
+          rehypePlugins: [rehypeKatex],
+          // highlight-end
+        },
+      },
+    ],
+  ],
+};
+```
+
+<details>
+  <summary>Using a [**CommonJS**](https://nodejs.org/api/modules.html#modules-commonjs-modules) config file?</summary>
+
+If you decide to use a CommonJS config file, it is possible to load those ES module plugins thanks to dynamic imports and an async config creator function:
 
 ```js title="docusaurus.config.js"
 // highlight-start
@@ -88,28 +118,30 @@ module.exports = async function createConfigAsync() {
 };
 ```
 
+</details>
+
 ## Configuring plugins {#configuring-plugins}
 
 Some plugins can be configured and accept their own options. In that case, use the `[plugin, pluginOptions]` syntax, like this:
 
 ```js title="docusaurus.config.js"
-module.exports = async function createConfigAsync() {
-  return {
-    presets: [
-      [
-        '@docusaurus/preset-classic',
-        {
-          docs: {
-            rehypePlugins: [
-              // highlight-start
-              [(await import('rehype-katex')).default, {strict: false}],
-              // highlight-end
-            ],
-          },
+import rehypeKatex from 'rehype-katex';
+
+export default {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          rehypePlugins: [
+            // highlight-start
+            [rehypeKatex, {strict: false}],
+            // highlight-end
+          ],
         },
-      ],
+      },
     ],
-  };
+  ],
 };
 ```
 
@@ -128,7 +160,7 @@ The writeup below is **not** meant to be a comprehensive guide to creating a plu
 For example, let's make a plugin that visits every `h2` heading and adds a `Section X. ` prefix. First, create your plugin source file anywhere—you can even publish it as a separate npm package and install it like explained above. We would put ours at `src/remark/section-prefix.js`. A remark/rehype plugin is just a function that receives the `options` and returns a `transformer` that operates on the AST.
 
 ```js "src/remark/section-prefix.js"
-const visit = require('unist-util-visit');
+import visit from 'unist-util-visit';
 
 const plugin = (options) => {
   const transformer = async (ast) => {
@@ -146,16 +178,16 @@ const plugin = (options) => {
   return transformer;
 };
 
-module.exports = plugin;
+export default plugin;
 ```
 
 You can now import your plugin in `docusaurus.config.js` and use it just like an installed plugin!
 
 ```js title="docusaurus.config.js"
 // highlight-next-line
-const sectionPrefix = require('./src/remark/section-prefix');
+import sectionPrefix from './src/remark/section-prefix';
 
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -195,7 +227,7 @@ Our `transformImage` plugin uses this parameter, for example, to transform relat
 The default plugins of Docusaurus would operate before the custom remark plugins, and that means the images or links have been converted to JSX with `require()` calls already. For example, in the example above, the table of contents generated is still the same even when all `h2` headings are now prefixed by `Section X.`, because the TOC-generating plugin is called before our custom plugin. If you need to process the MDAST before the default plugins do, use the `beforeDefaultRemarkPlugins` and `beforeDefaultRehypePlugins`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-react.mdx

@@ -229,7 +229,7 @@ If you don't wrap your imported MDX with `MDXContent`, the global scope will not
 
 Docusaurus v3 is using [MDX v2](https://mdxjs.com/blog/v2/).
 
-The [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) is mostly compatible with [CommonMark](https://commonmark.org/), but is much stricter because your `.mdx` files are compiled into real React components (check the [playground](https://mdxjs.com/playground/)).
+The [MDX syntax](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax) is mostly compatible with [CommonMark](https://commonmark.org/), but is much stricter because your `.mdx` files can use JSX and are compiled into real React components (check the [playground](https://mdxjs.com/playground/)).
 
 Some valid CommonMark features won't work with MDX ([more info](https://mdxjs.com/docs/what-is-mdx/#markdown)), notably:
 
@@ -238,12 +238,14 @@ Some valid CommonMark features won't work with MDX ([more info](https://mdxjs.co
 - HTML syntax (`<p style="color: red;">`): use JSX instead (`<p style={{color: 'red'}}>`)
 - Unescaped `{` and `<`: escape them with `\` instead (`\{` and `\<`)
 
-:::tip
+:::danger Experimental CommonMark support
 
-In case you need a less strict format, with [CommonMark](https://commonmark.org/) compatibility, you can use:
+Docusaurus v3 makes it possible to opt-in for a less strict, standard [CommonMark](https://commonmark.org/) support with the following options:
 
-- The `.md` file extension instead of `.mdx`
 - The `format: md` front matter
+- The `.md` file extension combined with the `siteConfig.markdown.format: "detect"` configuration
+
+This feature is **experimental** and currently has a few [limitations](https://github.com/facebook/docusaurus/issues/9092).
 
 :::
 

website/versioned_docs/version-3.0.0-rc.0/guides/markdown-features/markdown-features-toc.mdx

@@ -76,7 +76,7 @@ toc_max_heading_level: 5
 To set the heading level for _all_ pages, use the [`themeConfig.tableOfContents`](../../api/themes/theme-configuration.mdx#table-of-contents) option.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     tableOfContents: {
       // highlight-start

website/versioned_docs/version-3.0.0-rc.0/i18n/i18n-crowdin.mdx

@@ -59,7 +59,7 @@ npx create-docusaurus@latest website classic
 Add the site configuration for the French language:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fr'],
@@ -460,7 +460,7 @@ You may prefer the edit button to link to the Crowdin interface instead by using
 ```js title="docusaurus.config.js"
 const DefaultLocale = 'en';
 
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -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/versioned_docs/version-3.0.0-rc.0/i18n/i18n-git.mdx

@@ -20,7 +20,7 @@ This strategy has advantages:
 Using Git also present some shortcomings:
 
 - **Hard for non-developers**: they do not master Git and pull-requests
-- **Hard for professional translators**: they are used to SaaS translation softwares and advanced features
+- **Hard for professional translators**: they are used to SaaS translation software and advanced features
 - **Hard to maintain**: you have to keep the translated files **in sync** with the untranslated files
 
 :::note
@@ -46,7 +46,7 @@ npx create-docusaurus@latest website classic
 Add the site configuration for the French language:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fr'],

website/versioned_docs/version-3.0.0-rc.0/i18n/i18n-tutorial.mdx

@@ -26,7 +26,7 @@ Modify `docusaurus.config.js` to add the i18n support for the French language.
 Use the [site i18n configuration](./../api/docusaurus.config.js.mdx#i18n) to declare the i18n locales:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fr', 'fa'],
@@ -52,7 +52,7 @@ Docusaurus uses the locale names to provide **sensible defaults**: the `<html la
 Add a **navbar item** of type `localeDropdown` so that users can select the locale they want:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     navbar: {
       items: [
@@ -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/versioned_docs/version-3.0.0-rc.0/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/versioned_docs/version-3.0.0-rc.0/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/versioned_docs/version-3.0.0-rc.0/migration/v2/migration-automated.mdx

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

website/versioned_docs/version-3.0.0-rc.0/migration/v2/migration-manual.mdx

@@ -1,5 +1,5 @@
 ---
-slug: /migration/manual
+slug: /migration/v2/manual
 toc_max_heading_level: 4
 ---
 
@@ -207,7 +207,7 @@ Infima uses 7 shades of each color.
 
 We recommend using [ColorBox](https://www.colorbox.io/) to find the different shades of colors for your chosen primary color.
 
-Alteratively, use the following tool to generate the different shades for your website and copy the variables into `src/css/custom.css`.
+Alternatively, use the following tool to generate the different shades for your website and copy the variables into `src/css/custom.css`.
 
 import ColorGenerator from '@site/src/components/ColorGenerator';
 
@@ -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/versioned_docs/version-3.0.0-rc.0/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/versioned_docs/version-3.0.0-rc.0/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/versioned_docs/version-3.0.0-rc.0/migration/v2/migration-versioned-sites.mdx

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

website/versioned_docs/version-3.0.0-rc.0/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-rc.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).

website/versioned_docs/version-3.0.0-rc.0/search.mdx

@@ -49,7 +49,7 @@ After your application has been approved and deployed, you will receive an email
 
 :::tip
 
-It is highly recommended to use a config similar to the [**Docusaurus v3 website config**](https://docsearch.algolia.com/docs/templates/#docusaurus-v3-template).
+It is highly recommended to use a config similar to the [**Docusaurus v3 website config**](https://docsearch.algolia.com/docs/templates/#docusaurus-v2-template).
 
 :::
 
@@ -69,7 +69,7 @@ npm install --save @docusaurus/theme-search-algolia
 2. Register the theme in `docusaurus.config.js`:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   title: 'My site',
   // ...
   themes: ['@docusaurus/theme-search-algolia'],
@@ -84,7 +84,7 @@ module.exports = {
 Then, add an `algolia` field in your `themeConfig`. **[Apply for DocSearch](https://docsearch.algolia.com/apply/)** to get your Algolia index and API key.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   themeConfig: {
     // ...
@@ -146,7 +146,7 @@ Contextual search is **enabled by default**.
 It ensures that search results are **relevant to the current language and version**.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   themeConfig: {
     // ...
@@ -177,7 +177,7 @@ When using `contextualSearch: true` (default), the contextual facet filters will
 For specific needs, you can disable `contextualSearch` and define your own `facetFilters`:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   themeConfig: {
     // ...
@@ -252,7 +252,7 @@ Still, you can reuse the [Infima CSS variables](styling-layout.mdx#styling-your-
 Algolia DocSearch supports a [list of options](https://autocomplete-experimental.netlify.app/docs/DocSearchModal#reference) that you can pass to the `algolia` field in the `docusaurus.config.js` file.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // ...
     algolia: {

website/versioned_docs/version-3.0.0-rc.0/seo.mdx

@@ -17,7 +17,7 @@ Docusaurus supports search engine optimization in a variety of ways.
 Provide global meta attributes for the entire site through the [site configuration](./configuration.mdx#site-metadata). The metadata will all be rendered in the HTML `<head>` using the key-value pairs as the prop name and value. The `metadata` attribute is a convenient shortcut to declare `<meta>` tags, but it is also possible to inject arbitrary tags in `<head>` with the `headTags` attribute.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themeConfig: {
     // Declare some <meta> tags
     metadata: [

website/versioned_docs/version-3.0.0-rc.0/static-assets.mdx

@@ -16,7 +16,7 @@ This means that:
 You can customize the static directory sources in `docusaurus.config.js`. For example, we can add `public` as another possible path:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   title: 'My site',
   staticDirectories: ['public', 'static'],
   // ...

website/versioned_docs/version-3.0.0-rc.0/styling-layout.mdx

@@ -24,7 +24,7 @@ This is the most traditional way of styling that most developers (including non-
 If you're using `@docusaurus/preset-classic`, you can create your own CSS files (e.g. `/src/css/custom.css`) and import them globally by passing them as an option of the classic theme.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   presets: [
     [
@@ -32,7 +32,7 @@ module.exports = {
       {
         // highlight-start
         theme: {
-          customCss: [require.resolve('./src/css/custom.css')],
+          customCss: ['./src/css/custom.css'],
         },
         // highlight-end
       },
@@ -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):
 
@@ -234,7 +234,7 @@ npm install --save docusaurus-plugin-sass sass
 2. Include the plugin in your `docusaurus.config.js` file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-next-line
   plugins: ['docusaurus-plugin-sass'],
@@ -249,7 +249,7 @@ module.exports = {
 You can now set the `customCss` property of `@docusaurus/preset-classic` to point to your Sass/SCSS file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -257,7 +257,7 @@ module.exports = {
         // ...
         theme: {
           // highlight-next-line
-          customCss: [require.resolve('./src/css/custom.scss')],
+          customCss: ['./src/css/custom.scss'],
         },
         // ...
       },

website/versioned_docs/version-3.0.0-rc.0/typescript-support.mdx

@@ -6,6 +6,8 @@ description: Docusaurus is written in TypeScript and provides first-class TypeSc
 
 Docusaurus is written in TypeScript and provides first-class TypeScript support.
 
+The minimum required version is **TypeScript 5.0**.
+
 ## Initialization {#initialization}
 
 Docusaurus supports writing and using TypeScript theme components. If the init template provides a TypeScript variant, you can directly initialize a site with full TypeScript support by using the `--typescript` flag.
@@ -18,10 +20,10 @@ Below are some guides on how to migrate an existing project to TypeScript.
 
 ## Setup {#setup}
 
-To start using TypeScript, add `@docusaurus/module-type-aliases` and the base TS config to your project:
+Add the following packages to your project:
 
 ```bash npm2yarn
-npm install --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig
+npm install --save-dev typescript @docusaurus/module-type-aliases @docusaurus/tsconfig @docusaurus/types
 ```
 
 Then add `tsconfig.json` to your project root with the following content:
@@ -41,69 +43,84 @@ Now you can start writing TypeScript theme components.
 
 ## Typing the config file {#typing-config}
 
-It is **not possible** to use a TypeScript config file in Docusaurus unless you compile it yourself to JavaScript.
+It is possible to use a TypeScript config file in Docusaurus.
 
-We recommend using [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html):
+```ts title="docusaurus.config.ts"
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+// highlight-next-line
+const config: Config = {
+  title: 'My Site',
+  favicon: 'img/favicon.ico',
+
+  /* Your site config here */
+
+  presets: [
+    [
+      'classic',
+      {
+        /* Your preset config here */
+        // highlight-next-line
+      } satisfies Preset.Options,
+    ],
+  ],
+
+  themeConfig: {
+    /* Your theme config here */
+    // highlight-next-line
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;
+```
+
+<details>
+  <summary>It is also possible to use [JSDoc type annotations](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html) within a `.js` file:</summary>
+
+By default, the Docusaurus TypeScript config does not type-check JavaScript files.
+
+The `// @ts-check` comment ensures the config file is properly type-checked when running `npx tsc`.
 
 ```js title="docusaurus.config.js"
 // highlight-next-line
 // @ts-check
 
-// highlight-next-line
-/** @type {import('@docusaurus/types').Plugin} */
-function MyPlugin(context, options) {
-  return {
-    name: 'my-plugin',
-  };
-}
-
 // highlight-next-line
 /** @type {import('@docusaurus/types').Config} */
 const config = {
-  title: 'Docusaurus',
-  tagline: 'Build optimized websites quickly, focus on your content',
-  organizationName: 'facebook',
-  projectName: 'docusaurus',
-  plugins: [MyPlugin],
+  tagline: 'Dinosaurs are cool',
+  favicon: 'img/favicon.ico',
+
+  /* Your site config here */
+
   presets: [
     [
       '@docusaurus/preset-classic',
       // highlight-next-line
       /** @type {import('@docusaurus/preset-classic').Options} */
-      ({
-        docs: {
-          path: 'docs',
-          sidebarPath: 'sidebars.js',
-        },
-        blog: {
-          path: 'blog',
-          postsPerPage: 5,
-        },
-      }),
+      (
+        {
+          /* Your preset config here */
+        }
+      ),
     ],
   ],
   themeConfig:
     // highlight-next-line
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
-    ({
-      colorMode: {
-        defaultMode: 'dark',
-      },
-      navbar: {
-        hideOnScroll: true,
-        title: 'Docusaurus',
-        logo: {
-          alt: 'Docusaurus Logo',
-          src: 'img/docusaurus.svg',
-          srcDark: 'img/docusaurus_keytar.svg',
-        },
-      },
-    }),
+    (
+      {
+        /* Your theme config here */
+      }
+    ),
 };
 
-module.exports = config;
+export default config;
 ```
 
+</details>
+
 :::tip
 
 Type annotations are very useful and help your IDE understand the type of config objects!
@@ -112,14 +129,6 @@ The best IDEs (VS Code, WebStorm, IntelliJ...) will provide a nice auto-completi
 
 :::
 
-:::info
-
-By default, the Docusaurus TypeScript config does not type-check JavaScript files.
-
-The `// @ts-check` comment ensures the config file is properly type-checked when running `npx tsc`.
-
-:::
-
 ## Swizzling TypeScript theme components {#swizzling-typescript-theme-components}
 
 For themes that support TypeScript theme components, you can add the `--typescript` flag to the end of the `swizzle` command to get TypeScript source code. For example, the following command will generate `index.tsx` and `styles.module.css` into `src/theme/Footer`.

website/versioned_docs/version-3.0.0-rc.0/using-plugins.mdx

@@ -19,7 +19,7 @@ npm install --save docusaurus-plugin-name
 Then you add it in your site's `docusaurus.config.js`'s `plugins` option:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-next-line
   plugins: ['@docusaurus/plugin-content-pages'],
@@ -29,7 +29,7 @@ module.exports = {
 Docusaurus can also load plugins from your local directory, with something like the following:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-next-line
   plugins: ['./src/plugins/docusaurus-local-plugin'],
@@ -45,7 +45,7 @@ For the most basic usage of plugins, you can provide just the plugin name or the
 However, plugins can have options specified by wrapping the name and an options object in a two-member tuple inside your config. This style is usually called "Babel Style".
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   plugins: [
     // highlight-start
@@ -63,7 +63,7 @@ module.exports = {
 Example:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     // Basic usage.
     '@docusaurus/plugin-debug',
@@ -84,7 +84,7 @@ module.exports = {
 All Docusaurus content plugins can support multiple plugin instances. For example, it may be useful to have [multiple docs plugin instances](./guides/docs/docs-multi-instance.mdx) or [multiple blogs](./blog.mdx#multiple-blogs). It is required to assign a unique ID to each plugin instance, and by default, the plugin ID is `default`.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   plugins: [
     [
       '@docusaurus/plugin-content-docs',
@@ -123,7 +123,7 @@ The `themes` and `plugins` options lead to different [shorthand resolutions](#mo
 :::
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-next-line
   themes: ['@docusaurus/theme-classic', '@docusaurus/theme-live-codeblock'],
@@ -152,7 +152,7 @@ The classic preset is shipped by default to new Docusaurus websites created with
 The classic preset will relay each option entry to the respective plugin/theme.
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     [
       '@docusaurus/preset-classic',
@@ -161,7 +161,7 @@ module.exports = {
         debug: undefined,
         // Will be passed to @docusaurus/theme-classic.
         theme: {
-          customCss: [require.resolve('./src/css/custom.css')],
+          customCss: ['./src/css/custom.css'],
         },
         // Will be passed to @docusaurus/plugin-content-docs (false to disable)
         docs: {},
@@ -194,7 +194,7 @@ npm install --save @docusaurus/preset-classic
 Then, add it in your site's `docusaurus.config.js`'s `presets` option:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-next-line
   presets: ['@docusaurus/preset-classic'],
@@ -204,7 +204,7 @@ module.exports = {
 Preset paths can be relative to the config file:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   // ...
   // highlight-next-line
   presets: ['./src/presets/docusaurus-local-preset'],
@@ -216,7 +216,7 @@ module.exports = {
 A preset is a function with the same shape as the [plugin constructor](./api/plugin-methods/README.mdx#plugin-constructor). It should return an object of `{ plugins: PluginConfig[], themes: PluginConfig[] }`, in the same as how they are accepted in the site config. For example, you can specify a preset that includes the following themes and plugins:
 
 ```js title="src/presets/docusaurus-preset-multi-docs.js"
-module.exports = function preset(context, opts = {}) {
+export default function preset(context, opts = {}) {
   return {
     themes: [['docusaurus-theme-awesome', opts.theme]],
     plugins: [
@@ -227,13 +227,13 @@ module.exports = function preset(context, opts = {}) {
       ['@docusaurus/plugin-content-docs', {...opts.docs3, id: 'docs3'}],
     ],
   };
-};
+}
 ```
 
 Then in your Docusaurus config, you may configure the preset:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   presets: [
     // highlight-start
     [
@@ -253,7 +253,7 @@ module.exports = {
 This is equivalent of doing:
 
 ```js title="docusaurus.config.js"
-module.exports = {
+export default {
   themes: [['docusaurus-theme-awesome', {hello: 'world'}]],
   plugins: [
     ['@docusaurus/plugin-content-docs', {id: 'docs1', path: '/docs'}],