chore: port-2.0.0-rc.1 (#7782)

website/versioned_docs/version-2.0.0-beta.21/api/themes/theme-classic.md

@@ -1,20 +0,0 @@
----
-sidebar_position: 2
-id: theme-classic
-title: '📦 theme-classic'
-slug: '/api/themes/@docusaurus/theme-classic'
----
-
-The classic theme for Docusaurus.
-
-You can refer to the [theme configuration page](theme-configuration.md) for more details on the configuration.
-
-```bash npm2yarn
-npm install --save @docusaurus/theme-classic
-```
-
-:::tip
-
-If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
-
-:::

website/versioned_docs/version-2.0.0-beta.21/guides/docs/docs-create-doc.mdx

@@ -1,119 +0,0 @@
----
-id: create-doc
-title: Create a doc
-description: Create a Markdown Document
-slug: /create-doc
----
-
-Create a Markdown file, `greeting.md`, and place it under the `docs` directory.
-
-```bash
-website # root directory of your site
-├── docs
-│   └── greeting.md
-├── src
-│   └── pages
-├── docusaurus.config.js
-├── ...
-```
-
-At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
-
-```md
----
-id: greeting
-title: Hello
----
-
-## Hello from Docusaurus
-
-Are you ready to create the documentation site for your open source project?
-
-### Headers
-
-will show up on the table of contents on the upper right
-
-So that your users will know what this page is all about without scrolling down or even without reading too much.
-
-### Only h2 and h3 will be in the TOC by default.
-
-You can configure the TOC heading levels either per-document or in the theme configuration.
-
-The headers are well-spaced so that the hierarchy is clear.
-
-- lists will help you
-- present the key points
-- that you want your users to remember
-  - and you may nest them
-    - multiple times
-
-### Custom id headers {#custom-id}
-
-With `{#custom-id}` syntax you can set your own header id.
-```
-
-This will render in the browser as follows:
-
-```mdx-code-block
-import BrowserWindow from '@site/src/components/BrowserWindow';
-
-<BrowserWindow>
-
-<h2>Hello from Docusaurus</h2>
-
-Are you ready to create the documentation site for your open source project?
-
-<h3>Headers</h3>
-
-will show up on the table of contents on the upper right
-
-So that your users will know what this page is all about without scrolling down or even without reading too much.
-
-<h3>Only h2 and h3 will be in the TOC by default.</h3>
-
-You can configure the TOC heading levels either per document or in the theme configuration.
-
-The headers are well-spaced so that the hierarchy is clear.
-
-- lists will help you
-- present the key points
-- that you want your users to remember
-  - and you may nest them
-    - multiple times
-
-<h3 id="custom-id">Custom id headers</h3>
-
-With <code>{#custom-id}</code> syntax you can set your own header id.
-
-</BrowserWindow>
-```
-
-:::note
-
-All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.
-
-Read more about [importing partial pages](../markdown-features/markdown-features-react.mdx#importing-markdown).
-
-:::
-
-## Doc tags {#doc-tags}
-
-Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.md). Tags are passed in the front matter as a list of labels:
-
-```md "your-doc-page.md"
----
-id: doc-with-tags
-title: A doc with tags
-tags:
-  - Demo
-  - Getting started
----
-```
-
-:::tip
-
-Tags can also be declared with `tags: [Demo, Getting started]`.
-
-Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).
-
-:::

website/versioned_docs/version-2.0.0-rc.1/advanced/routing.md

@@ -81,7 +81,7 @@ When writing links in Markdown, you could either mean a _file path_, or a _URL p
 - If the path has an `.md(x)` extension, Docusaurus would try to resolve that Markdown file to a URL, and replace the file path with a URL path.
 - If the path has any other extension, Docusaurus would treat it as [an asset](../guides/markdown-features/markdown-features-assets.mdx) and bundle it.
 
-The following directory structure may help you visualize this file -> URL mapping. Assume that there's no slug customization in any page.
+The following directory structure may help you visualize this file → URL mapping. Assume that there's no slug customization in any page.
 
 <details>
 

website/versioned_docs/version-2.0.0-rc.1/advanced/ssg.md

@@ -8,12 +8,14 @@ description: Docusaurus statically renders your React code into HTML, allowing f
 In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice:
 
 - During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages.
-- During **client-side rendering**, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript.
+- During **client-side rendering**, the theme is compiled to JavaScript that gets eventually executed in the browser, so it has access to browser variables.
 
 :::info SSR or SSG?
 
 _Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably.
 
+Strictly speaking, Docusaurus is a static site generator, because there's no server-side runtime—we statically render to HTML files that are deployed on a CDN, instead of dynamically pre-rendering on each request. This differs from the working model of [Next.js](https://nextjs.org/).
+
 :::
 
 Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either.
@@ -34,9 +36,10 @@ ReferenceError: window is not defined
 
 This is because during server-side rendering, the Docusaurus app isn't actually run in browser, and it doesn't know what `window` is.
 
+```mdx-code-block
 <details id="node-env">
-
 <summary>What about <code>process.env.NODE_ENV</code>?</summary>
+```
 
 One exception to the "no Node globals" rule is `process.env.NODE_ENV`. In fact, you can use it in React, because Webpack injects this variable as a global:
 
@@ -56,8 +59,10 @@ During Webpack build, the `process.env.NODE_ENV` will be replaced with the value
 
 import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Development">
+```
 
 ```diff
 import React from 'react';
@@ -72,8 +77,10 @@ export default function expensiveComp() {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="Production">
+```
 
 ```diff
 import React from 'react';
@@ -88,9 +95,11 @@ export default function expensiveComp() {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
 </details>
+```
 
 ## Understanding SSR {#understanding-ssr}
 

website/versioned_docs/version-2.0.0-rc.1/api/docusaurus.config.js.md

@@ -1,6 +1,5 @@
 ---
 sidebar_position: 0
-id: docusaurus.config.js
 description: API reference for Docusaurus configuration file.
 slug: /api/docusaurus-config
 ---
@@ -64,7 +63,7 @@ module.exports = {
 
 - Type: `string`
 
-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.
+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 = {
@@ -76,7 +75,7 @@ module.exports = {
 
 - Type: `string`
 
-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.
+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 = {
@@ -131,18 +130,21 @@ module.exports = {
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fa'],
+    path: 'i18n',
     localeConfigs: {
       en: {
         label: 'English',
         direction: 'ltr',
         htmlLang: 'en-US',
         calendar: 'gregory',
+        path: 'en',
       },
       fa: {
         label: 'فارسی',
         direction: 'rtl',
         htmlLang: 'fa-IR',
         calendar: 'persian',
+        path: 'fa',
       },
     },
   },
@@ -151,11 +153,13 @@ module.exports = {
 
 - `defaultLocale`: The locale that (1) does not have its name in the base URL (2) gets started with `docusaurus start` without `--locale` option (3) will be used for the `<link hrefLang="x-default">` tag
 - `locales`: List of locales deployed on your site. Must contain `defaultLocale`.
+- `path`: Root folder which all locale folders are relative to. Can be absolute or relative to the config file. Defaults to `i18n`.
 - `localeConfigs`: Individual options for each locale.
   - `label`: The label displayed for this locale in the locales dropdown.
-  - `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Farsi, Arabic, Hebrew, etc.). Used to select the locale's CSS and html meta attribute.
+  - `direction`: `ltr` (default) or `rtl` (for [right-to-left languages](https://developer.mozilla.org/en-US/docs/Glossary/rtl) like Farsi, Arabic, Hebrew, etc.). Used to select the locale's CSS and HTML meta attribute.
   - `htmlLang`: BCP 47 language tag to use in `<html lang="...">` and in `<link ... hreflang="...">`
   - `calendar`: the [calendar](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar) used to calculate the date era. Note that it doesn't control the actual string displayed: `MM/DD/YYYY` and `DD/MM/YYYY` are both `gregory`. To choose the format (`DD/MM/YYYY` or `MM/DD/YYYY`), set your locale name to `en-GB` or `en-US` (`en` means `en-US`).
+  - `path`: Root folder that all plugin localization folders of this locale are relative to. Will be resolved against `i18n.path`. Defaults to the locale's name. Note: this has no effect on the locale's `baseUrl`—customization of base URL is a work-in-progress.
 
 ### `noIndex` {#noIndex}
 
@@ -173,7 +177,7 @@ module.exports = {
 
 ### `onBrokenLinks` {#onBrokenLinks}
 
-- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
+- Type: `'ignore' | 'log' | 'warn' | 'throw'`
 
 The behavior of Docusaurus when it detects any broken link.
 
@@ -187,15 +191,15 @@ The broken links detection is only available for a production build (`docusaurus
 
 ### `onBrokenMarkdownLinks` {#onBrokenMarkdownLinks}
 
-- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
+- Type: `'ignore' | 'log' | 'warn' | 'throw'`
 
-The behavior of Docusaurus when it detects any broken markdown link.
+The behavior of Docusaurus when it detects any broken Markdown link.
 
-By default, it prints a warning, to let you know about your broken markdown link, but you can change this security if needed.
+By default, it prints a warning, to let you know about your broken Markdown link, but you can change this security if needed.
 
 ### `onDuplicateRoutes` {#onDuplicateRoutes}
 
-- Type: `'ignore' | 'log' | 'warn' | 'error' | 'throw'`
+- Type: `'ignore' | 'log' | 'warn' | 'throw'`
 
 The behavior of Docusaurus when it detects any [duplicate routes](/guides/creating-pages.md#duplicate-routes).
 
@@ -330,8 +334,9 @@ module.exports = {
         // ... other links
       ],
       logo: {
-        alt: 'Facebook Open Source Logo',
-        src: 'https://docusaurus.io/img/oss_logo.png',
+        alt: 'Meta Open Source Logo',
+        src: 'img/meta_oss_logo.png',
+        href: 'https://opensource.fb.com',
         width: 160,
         height: 51,
       },
@@ -426,7 +431,7 @@ module.exports = {
 
 ### `scripts` {#scripts}
 
-An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`.
+An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. If you use a plain object, the only required attribute is `src`, and any other attributes are permitted (each one should have boolean/string values).
 
 Note that `<script>` added here are render-blocking, so you might want to add `async: true`/`defer: true` to the objects.
 
@@ -450,7 +455,7 @@ module.exports = {
 
 ### `stylesheets` {#stylesheets}
 
-An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`.
+An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`. If you use an object, the only required attribute is `href`, and any other attributes are permitted (each one should have boolean/string values).
 
 - Type: `(string | Object)[]`
 
@@ -469,6 +474,12 @@ module.exports = {
 };
 ```
 
+:::info
+
+By default, the `<link>` tags will have `rel="stylesheet"`, but you can explicitly add a custom `rel` value to inject any kind of `<link>` tag, not necessarily stylesheets.
+
+:::
+
 ### `clientModules` {#clientModules}
 
 An array of [client modules](../advanced/client.md#client-modules) to load globally on your site.
@@ -542,7 +553,7 @@ module.exports = {
 };
 ```
 
-### `baseUrlIssueBanner` {#baseurlIssueBanner}
+### `baseUrlIssueBanner` {#baseUrlIssueBanner}
 
 - Type: `boolean`
 

website/versioned_docs/version-2.0.0-rc.1/api/misc/create-docusaurus.md

@@ -1,9 +1,10 @@
 ---
 sidebar_position: 0
-title: '📦 create-docusaurus'
-slug: '/api/misc/create-docusaurus'
+slug: /api/misc/create-docusaurus
 ---
 
+# 📦 create-docusaurus
+
 A scaffolding utility to help you instantly set up a functional Docusaurus app.
 
 ## Usage {#usage}

website/versioned_docs/version-2.0.0-rc.1/api/misc/eslint-plugin/README.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 1
-id: eslint-plugin
-title: '📦 eslint-plugin'
-slug: '/api/misc/@docusaurus/eslint-plugin'
+slug: /api/misc/@docusaurus/eslint-plugin
 ---
 
+# 📦 eslint-plugin
+
 [ESLint](https://eslint.org/) is a tool that statically analyzes your code and reports problems or suggests best practices through editor hints and command line. Docusaurus provides an ESLint plugin to enforce best Docusaurus practices.
 
 ## Installation

website/versioned_docs/version-2.0.0-rc.1/api/misc/eslint-plugin/no-untranslated-text.md

@@ -1,5 +1,5 @@
 ---
-slug: '/api/misc/@docusaurus/eslint-plugin/no-untranslated-text'
+slug: /api/misc/@docusaurus/eslint-plugin/no-untranslated-text
 ---
 
 # no-untranslated-text
@@ -32,13 +32,17 @@ Examples of **correct** code for this rule:
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `ignoredStrings` | `string[]` | `[]` | Text labels that only contain strings in this list will not be reported. |
 
+```mdx-code-block
 </APITable>
+```
 
 ## When Not To Use It {#when-not-to-use}
 

website/versioned_docs/version-2.0.0-rc.1/api/misc/eslint-plugin/string-literal-i18n-messages.md

@@ -1,5 +1,5 @@
 ---
-slug: '/api/misc/@docusaurus/eslint-plugin/string-literal-i18n-messages'
+slug: /api/misc/@docusaurus/eslint-plugin/string-literal-i18n-messages
 ---
 
 # string-literal-i18n-messages

website/versioned_docs/version-2.0.0-rc.1/api/misc/logger/logger.md

@@ -1,9 +1,10 @@
 ---
 sidebar_position: 2
-title: '📦 logger'
-slug: '/api/misc/@docusaurus/logger'
+slug: /api/misc/@docusaurus/logger
 ---
 
+# 📦 logger
+
 An encapsulated logger for semantically formatting console messages.
 
 Authors of packages in the Docusaurus ecosystem are encouraged to use this package to provide unified log formats.
@@ -31,6 +32,7 @@ It exports a single object as default export: `logger`. `logger` has the followi
   - `warn`: prints a warning that should be payed attention to.
   - `error`: prints an error (not necessarily halting the program) that signals significant problems.
   - `success`: prints a success message.
+- The `report` function. It takes a `ReportingSeverity` value (`ignore`, `log`, `warn`, `throw`) and reports a message according to the severity.
 
 :::caution A word on the `error` formatter
 

website/versioned_docs/version-2.0.0-rc.1/api/plugin-methods/i18n-lifecycles.md

@@ -103,7 +103,7 @@ module.exports = function (context, options) {
 
 Themes using the `<Translate>` API can provide default code translation messages.
 
-It should return messages in `Record<string, string>`, where keys are translation ids and values are messages (without the description) localized using the site's current locale.
+It should return messages in `Record<string, string>`, where keys are translation IDs and values are messages (without the description) localized using the site's current locale.
 
 Example:
 

website/versioned_docs/version-2.0.0-rc.1/api/plugin-methods/lifecycle-apis.md

@@ -178,7 +178,7 @@ The API of `configureWebpack` will be modified in the future to accept an object
 - `getStyleLoaders(isServer: boolean, cssOptions: {[key: string]: any}): Loader[]`
 - `getJSLoader(isServer: boolean, cacheOptions?: {}): Loader | null`
 
-You may use them to return your webpack configures conditionally.
+You may use them to return your webpack configuration conditionally.
 
 For example, this plugin below modify the webpack config to transpile `.foo` files.
 

website/versioned_docs/version-2.0.0-rc.1/api/plugins/overview.md

@@ -1,11 +1,12 @@
 ---
 sidebar_position: 0
 id: plugins-overview
-title: 'Docusaurus plugins'
 sidebar_label: Plugins overview
-slug: '/api/plugins'
+slug: /api/plugins
 ---
 
+# Docusaurus plugins
+
 We provide official Docusaurus plugins.
 
 ## Content plugins {#content-plugins}

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-client-redirects.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 4
-id: plugin-client-redirects
-title: '📦 plugin-client-redirects'
-slug: '/api/plugins/@docusaurus/plugin-client-redirects'
+slug: /api/plugins/@docusaurus/plugin-client-redirects
 ---
 
+# 📦 plugin-client-redirects
+
 import APITable from '@site/src/components/APITable';
 
 Docusaurus Plugin to generate **client-side redirects**.
@@ -35,16 +35,26 @@ npm install --save @docusaurus/plugin-client-redirects
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `fromExtensions` | `string[]` | `[]` | The extensions to be removed from the route after redirecting. |
 | `toExtensions` | `string[]` | `[]` | The extensions to be appended to the route after redirecting. |
 | `redirects` | <code><a href="#RedirectRule">RedirectRule</a>[]</code> | `[]` | The list of redirect rules. |
-| `createRedirects` | <code><a href="#CreateRedirectsFn">CreateRedirectsFn</a></code> | `undefined` | A callback to create a redirect rule. |
+| `createRedirects` | <code><a href="#CreateRedirectsFn">CreateRedirectsFn</a></code> | `undefined` | A callback to create a redirect rule. Docusaurus query this callback against every path it has created, and use its return value to output more paths. |
 
+```mdx-code-block
 </APITable>
+```
+
+:::note
+
+This plugin will also read the [`siteConfig.onDuplicateRoutes`](../docusaurus.config.js.md#onDuplicateRoutes) config to adjust its logging level when multiple files will be emitted to the same location.
+
+:::
 
 ### Types {#types}
 
@@ -57,9 +67,20 @@ type RedirectRule = {
 };
 ```
 
+:::note
+
+The idea of "from" and "to" is central in this plugin. "From" means a path that you want to _create_, i.e. an extra HTML file that will be written; "to" means a path to want to redirect _to_, usually a route that Docusaurus already knows about.
+
+This is why you can have multiple "from" for the same "to": we will create multiple HTML files that all redirect to the same destination. On the other hand, one "from" can never have more than one "to": the written HTML file needs to have a determinate destination.
+
+:::
+
 #### `CreateRedirectsFn` {#CreateRedirectsFn}
 
 ```ts
+// The parameter `path` is a route that Docusaurus has already created. It can
+// be seen as the "to", and your return value is the "from". Returning a falsy
+// value will not create any redirect pages for this particular path.
 type CreateRedirectsFn = (path: string) => string[] | string | null | undefined;
 ```
 

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-content-blog.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 2
-id: plugin-content-blog
-title: '📦 plugin-content-blog'
-slug: '/api/plugins/@docusaurus/plugin-content-blog'
+slug: /api/plugins/@docusaurus/plugin-content-blog
 ---
 
+# 📦 plugin-content-blog
+
 import APITable from '@site/src/components/APITable';
 
 Provides the [Blog](blog.mdx) feature and is the default blog plugin for Docusaurus.
@@ -33,7 +33,9 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -71,7 +73,9 @@ Accepted fields:
 | `feedOptions.language` | `string` (See [documentation](http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes) for possible values) | `undefined` | Language metadata of the feed. |
 | `sortPosts` | <code>'descending' \| 'ascending' </code> | `'descending'` | Governs the direction of blog post sorting. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Types {#types}
 
@@ -174,7 +178,9 @@ Markdown documents can use the following Markdown front matter metadata fields,
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -193,9 +199,11 @@ Accepted fields:
 | `keywords` | `string[]` | `undefined` | Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines. |
 | `description` | `string` | The first line of Markdown content | The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. |
 | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
-| `slug` | `string` | File path | Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. |
+| `slug` | `string` | File path | Allows to customize the blog post URL (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-blog-post`, `slug: /my/path/to/blog/post`, slug: `/`. |
 
+```mdx-code-block
 </APITable>
+```
 
 ```ts
 type Tag = string | {label: string; permalink: string};

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-content-docs.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 1
-id: plugin-content-docs
-title: '📦 plugin-content-docs'
-slug: '/api/plugins/@docusaurus/plugin-content-docs'
+slug: /api/plugins/@docusaurus/plugin-content-docs
 ---
 
+# 📦 plugin-content-docs
+
 import APITable from '@site/src/components/APITable';
 
 Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
@@ -27,7 +27,9 @@ You can configure this plugin through the preset options.
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -62,7 +64,9 @@ Accepted fields:
 | `onlyIncludeVersions` | `string[]` | All versions available | Only include a subset of all available versions. |
 | `versions` | <a href="#VersionsConfig"><code>VersionsConfig</code></a> | `{}` | Independent customization of each version's properties. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Types {#types}
 
@@ -257,16 +261,19 @@ Markdown documents can use the following Markdown front matter metadata fields,
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| `id` | `string` | file path (including folders, without the extension) | A unique document id. |
+| `id` | `string` | file path (including folders, without the extension) | A unique document ID. |
 | `title` | `string` | Markdown title or `id` | The text title of your document. Used for the page metadata and as a fallback value in multiple places (sidebar, next/previous buttons...). Automatically added at the top of your doc if it does not contain any Markdown title. |
 | `pagination_label` | `string` | `sidebar_label` or `title` | The text used in the document next/previous buttons for this document. |
 | `sidebar_label` | `string` | `title` | The text shown in the document sidebar for this document. |
 | `sidebar_position` | `number` | Default ordering | Controls the position of a doc inside the generated sidebar slice when using `autogenerated` sidebar items. See also [Autogenerated sidebar metadata](/docs/sidebar#autogenerated-sidebar-metadata). |
 | `sidebar_class_name` | `string` | `undefined` | Gives the corresponding sidebar label a special class name when using autogenerated sidebars. |
+| `sidebar_custom_props` | `string` | `undefined` | Assign custom metadata to the sidebar item referencing this doc. |
 | `hide_title` | `boolean` | `false` | Whether to hide the title at the top of the doc. It only hides a title declared through the front matter, and have no effect on a Markdown title at the top of your document. |
 | `hide_table_of_contents` | `boolean` | `false` | Whether to hide the table of contents to the right. |
 | `toc_min_heading_level` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
@@ -278,16 +285,23 @@ Accepted fields:
 | `keywords` | `string[]` | `undefined` | Keywords meta tag for the document page, for search engines. |
 | `description` | `string` | The first line of Markdown content | The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. |
 | `image` | `string` | `undefined` | Cover or thumbnail image that will be used when displaying the link to your post. |
-| `slug` | `string` | File path | Allows to customize the document url (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
+| `slug` | `string` | File path | Allows to customize the document URL (`/<routeBasePath>/<slug>`). Support multiple patterns: `slug: my-doc`, `slug: /my/path/myDoc`, `slug: /`. |
 | `tags` | `Tag[]` | `undefined` | A list of strings or objects of two string fields `label` and `permalink` to tag to your docs. |
 | `draft` | `boolean` | `false` | A boolean flag to indicate that a document is a work-in-progress. Draft documents will only be displayed during development. |
+| `last_update` | `FileChange` | `undefined` | Allows overriding the last updated author and/or date. Date can be any [parsable date string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/parse). |
 
+```mdx-code-block
 </APITable>
+```
 
 ```ts
 type Tag = string | {label: string; permalink: string};
 ```
 
+```ts
+type FileChange = {date: string; author: string};
+```
+
 Example:
 
 ```md
@@ -306,6 +320,9 @@ keywords:
   - docusaurus
 image: https://i.imgur.com/mErPwqL.png
 slug: /myDoc
+last_update:
+  date: 1/1/2000
+  author: custom author name
 ---
 
 # Markdown Features

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-content-pages.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 3
-id: plugin-content-pages
-title: '📦 plugin-content-pages'
-slug: '/api/plugins/@docusaurus/plugin-content-pages'
+slug: /api/plugins/@docusaurus/plugin-content-pages
 ---
 
+# 📦 plugin-content-pages
+
 import APITable from '@site/src/components/APITable';
 
 The default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides [creating pages](guides/creating-pages.md) functionality.
@@ -27,7 +27,9 @@ You can configure this plugin through the preset options.
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -41,7 +43,9 @@ Accepted fields:
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
 | `beforeDefaultRehypePlugins` | `any[]` | `[]` | Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Example configuration {#ex-config}
 

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-debug.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 5
-id: plugin-debug
-title: '📦 plugin-debug'
-slug: '/api/plugins/@docusaurus/plugin-debug'
+slug: /api/plugins/@docusaurus/plugin-debug
 ---
 
+# 📦 plugin-debug
+
 ```mdx-code-block
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -67,8 +67,10 @@ Most Docusaurus users configure this plugin through the preset options.
 
 :::
 
-<Tabs>
-<TabItem value="Preset Options">
+```mdx-code-block
+<Tabs groupId="api-config-ex">
+<TabItem value="preset" label="Preset options">
+```
 
 If you use a preset, configure this plugin through the [preset options](../../using-plugins.md#docusauruspreset-classic):
 
@@ -86,8 +88,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
-<TabItem value="Plugin Options">
+<TabItem value="plugin" label="Plugin Options">
+```
 
 If you are using a standalone plugin, provide options directly to the plugin:
 
@@ -98,5 +102,7 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-google-analytics.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 6
-id: plugin-google-analytics
-title: '📦 plugin-google-analytics'
-slug: '/api/plugins/@docusaurus/plugin-google-analytics'
+slug: /api/plugins/@docusaurus/plugin-google-analytics
 ---
 
+# 📦 plugin-google-analytics
+
 import APITable from '@site/src/components/APITable';
 
 The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead.
@@ -33,14 +33,18 @@ You can configure this plugin through the preset options.
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `trackingID` | `string` | **Required** | The tracking ID of your analytics service. |
 | `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Example configuration {#ex-config}
 

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-google-gtag.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 7
-id: plugin-google-gtag
-title: '📦 plugin-google-gtag'
-slug: '/api/plugins/@docusaurus/plugin-google-gtag'
+slug: /api/plugins/@docusaurus/plugin-google-gtag
 ---
 
+# 📦 plugin-google-gtag
+
 import APITable from '@site/src/components/APITable';
 
 The default [Global Site Tag (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.
@@ -39,14 +39,18 @@ You can configure this plugin through the preset options.
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `trackingID` | `string` | **Required** | The tracking ID of your gtag service. |
 | `anonymizeIP` | `boolean` | `false` | Whether the IP should be anonymized when sending requests. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Example configuration {#ex-config}
 

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-ideal-image.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 8
-id: plugin-ideal-image
-title: '📦 plugin-ideal-image'
-slug: '/api/plugins/@docusaurus/plugin-ideal-image'
+slug: /api/plugins/@docusaurus/plugin-ideal-image
 ---
 
+# 📦 plugin-ideal-image
+
 import APITable from '@site/src/components/APITable';
 
 Docusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder).
@@ -40,7 +40,9 @@ import thumbnail from './path/to/img.png';
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -53,7 +55,9 @@ Accepted fields:
 | `quality` | `number` | `85` | JPEG compression quality |
 | `disableInDev` | `boolean` | `true` | You can test ideal image behavior in dev mode by setting this to `false`. **Tip**: use [network throttling](https://www.browserstack.com/guide/how-to-perform-network-throttling-in-chrome) in your browser to simulate slow networks. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Example configuration {#ex-config}
 

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-pwa.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 9
-id: plugin-pwa
-title: '📦 plugin-pwa'
-slug: '/api/plugins/@docusaurus/plugin-pwa'
+slug: /api/plugins/@docusaurus/plugin-pwa
 ---
 
+# 📦 plugin-pwa
+
 Docusaurus Plugin to add PWA support using [Workbox](https://developers.google.com/web/tools/workbox). This plugin generates a [Service Worker](https://developers.google.com/web/fundamentals/primers/service-workers) in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.
 
 ## Installation {#installation}
@@ -70,7 +70,7 @@ If your browser supports it, you should be able to install a Docusaurus site as
 
 :::note
 
-App installation requires the https protocol and a valid manifest.
+App installation requires the HTTPS protocol and a valid manifest.
 
 :::
 
@@ -120,7 +120,7 @@ Strategies used to turn the offline mode on:
 - `appInstalled`: activates for users having installed the site as an app (not 100% reliable)
 - `standalone`: activates for users running the app as standalone (often the case once a PWA is installed)
 - `queryString`: activates if queryString contains `offlineMode=true` (convenient for PWA debugging)
-- `mobile`: activates for mobile users (width <= 940px)
+- `mobile`: activates for mobile users (width <= 996px)
 - `saveData`: activates for users with `navigator.connection.saveData === true`
 - `always`: activates for all users
 
@@ -160,7 +160,7 @@ module.exports = {
           modifyURLPrefix: {
             //...
           },
-          // We already add regular static assets (html, images...) to be available offline
+          // We already add regular static assets (HTML, images...) to be available offline
           // You can add more files according to your needs
           globPatterns: ['**/*.{pdf,docx,xlsx}'],
           // ...

website/versioned_docs/version-2.0.0-rc.1/api/plugins/plugin-sitemap.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 10
-id: plugin-sitemap
-title: '📦 plugin-sitemap'
-slug: '/api/plugins/@docusaurus/plugin-sitemap'
+slug: /api/plugins/@docusaurus/plugin-sitemap
 ---
 
+# 📦 plugin-sitemap
+
 import APITable from '@site/src/components/APITable';
 
 This plugin creates sitemaps for your site so that search engine crawlers can crawl your site more accurately.
@@ -33,7 +33,9 @@ You can configure this plugin through the [preset options](#ex-config-preset).
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -42,7 +44,9 @@ Accepted fields:
 | `ignorePatterns` | `string[]` | `[]` | A list of glob patterns; matching route paths will be filtered from the sitemap. Note that you may need to include the base URL in here. |
 | `filename` | `string` | `sitemap.xml` | The path to the created sitemap file, relative to the output directory. Useful if you have two plugin instances outputting two files. |
 
+```mdx-code-block
 </APITable>
+```
 
 :::info
 

website/versioned_docs/version-2.0.0-rc.1/api/themes/overview.md

@@ -1,11 +1,12 @@
 ---
 sidebar_position: 0
 id: themes-overview
-title: 'Docusaurus themes'
 sidebar_label: Themes overview
-slug: '/api/themes'
+slug: /api/themes
 ---
 
+# Docusaurus themes
+
 We provide official Docusaurus themes.
 
 ## Main themes {#main-themes}

website/versioned_docs/version-2.0.0-rc.1/api/themes/theme-classic.md

@@ -0,0 +1,61 @@
+---
+sidebar_position: 2
+slug: /api/themes/@docusaurus/theme-classic
+---
+
+# 📦 theme-classic
+
+The classic theme for Docusaurus.
+
+You can refer to the [theme configuration page](theme-configuration.md) for more details on the configuration.
+
+```bash npm2yarn
+npm install --save @docusaurus/theme-classic
+```
+
+:::tip
+
+If you have installed `@docusaurus/preset-classic`, you don't need to install it as a dependency.
+
+:::
+
+## Configuration {#configuration}
+
+Accepted fields:
+
+```mdx-code-block
+<APITable>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `customCss` | <code>string[] \| string</code> | `[]` | Stylesheets to be imported globally as [client modules](../../advanced/client.md#client-modules). Relative paths are resolved against the site directory. |
+
+```mdx-code-block
+</APITable>
+```
+
+:::note
+
+Most configuration for the theme is done in `themeConfig`, which can be found in [theme configuration](./theme-configuration.md).
+
+:::
+
+### Example configuration {#ex-config}
+
+You can configure this theme through preset options or plugin options.
+
+:::tip
+
+Most Docusaurus users configure this plugin through the preset options.
+
+:::
+
+```js config-tabs
+// Preset Options: theme
+// Plugin Options: @docusaurus/theme-classic
+
+const config = {
+  customCss: require.resolve('./src/css/custom.css'),
+};
+```

website/versioned_docs/version-2.0.0-rc.1/api/themes/theme-configuration.md

@@ -1,12 +1,12 @@
 ---
 sidebar_position: 1
-id: theme-configuration
-title: 'Theme configuration'
-sidebar_label: 'Configuration'
-slug: '/api/themes/configuration'
+sidebar_label: Configuration
+slug: /api/themes/configuration
 toc_max_heading_level: 4
 ---
 
+# Theme configuration
+
 import APITable from '@site/src/components/APITable';
 
 This configuration applies to all [main themes](./overview.md).
@@ -21,7 +21,9 @@ It is possible to customize the color mode support within the `colorMode` object
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -29,7 +31,9 @@ Accepted fields:
 | `disableSwitch` | `boolean` | `false` | Hides the switch in the navbar. Useful if you want to support a single color mode. |
 | `respectPrefersColorScheme` | `boolean` | `false` | Whether to use the `prefers-color-scheme` media-query, using user system preferences, instead of the hardcoded `defaultMode`. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -61,13 +65,17 @@ You can configure a default image that will be used for your meta tag, in partic
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `image` | `string` | `undefined` | The meta image URL for the site. Relative to your site's "static" directory. Cannot be SVGs. Can be external URLs too. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -82,17 +90,21 @@ module.exports = {
 
 ### Metadata {#metadata}
 
-You can configure additional html metadata (and override existing ones).
+You can configure additional HTML metadata (and override existing ones).
 
 Accepted fields:
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `metadata` | `Metadata[]` | `[]` | Any field will be directly passed to the `<meta />` tag. Possible fields include `id`, `name`, `property`, `content`, `itemprop`, etc. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -111,7 +123,9 @@ Sometimes you want to announce something in your website. Just for such a case,
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="announcement-bar">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -121,7 +135,9 @@ Accepted fields:
 | `textColor` | `string` | `'#000'` | Announcement text color. |
 | `isCloseable` | `boolean` | `true` | Whether this announcement can be dismissed with a '×' button. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -146,7 +162,9 @@ module.exports = {
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-overview">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -156,7 +174,9 @@ Accepted fields:
 | `hideOnScroll` | `boolean` | `false` | Whether the navbar is hidden when the user scrolls down. |
 | `style` | <code>'primary' \| 'dark'</code> | Same as theme | Sets the navbar style, ignoring the dark/light theme. |
 
+```mdx-code-block
 </APITable>
+```
 
 ### Navbar logo {#navbar-logo}
 
@@ -166,7 +186,9 @@ To improve dark mode support, you can also set a different logo for this mode.
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-logo">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -177,8 +199,12 @@ Accepted fields:
 | `width` | <code>string \| number</code> | `undefined` | Specifies the `width` attribute. |
 | `height` | <code>string \| number</code> | `undefined` | Specifies the `height` attribute. |
 | `target` | `string` | Calculated based on `href` (external links will open in a new tab, all others in the current one). | The `target` attribute of the link; controls whether the link is opened in a new tab, the current one, or otherwise. |
+| `className` | `string` | `undefined` | CSS class applied to the image. |
+| `style` | `object` | `undefined` | CSS inline style object. React/JSX flavor, using camelCase properties. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -196,6 +222,8 @@ module.exports = {
         target: '_self',
         width: 32,
         height: 32,
+        className: 'custom-navbar-logo-class',
+        style: {border: 'solid red'},
       },
       // highlight-end
     },
@@ -253,7 +281,9 @@ Outbound (external) links automatically get `target="_blank" rel="noopener noref
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-link">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -268,7 +298,9 @@ Accepted fields:
 | `activeBaseRegex` | `string` | `undefined` | Alternative to `activeBasePath` if required. |
 | `className` | `string` | `''` | Custom CSS class (for styling any item). |
 
+```mdx-code-block
 </APITable>
+```
 
 :::note
 
@@ -318,7 +350,9 @@ Note that the dropdown base item is a clickable link as well, so this item can r
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-dropdown">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -327,7 +361,9 @@ Accepted fields:
 | `items` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | **Required** | The items to be contained in the dropdown. |
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -367,7 +403,9 @@ If you want to link to a specific doc, this special navbar item type will render
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-doc-link">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -377,7 +415,9 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc belongs to. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -406,7 +446,9 @@ You can link a navbar item to the first document link (which can be a doc link o
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-doc-sidebar">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -416,7 +458,9 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the sidebar belongs to. |
 
+```mdx-code-block
 </APITable>
+```
 
 :::tip
 
@@ -469,11 +513,13 @@ module.exports = {
 
 If you use docs with versioning, this special navbar item type that will render a dropdown with all your site's available versions.
 
-The user will be able to switch from one version to another, while staying on the same doc (as long as the doc id is constant across versions).
+The user will be able to switch from one version to another, while staying on the same doc (as long as the doc ID is constant across versions).
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-docs-version-dropdown">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -484,7 +530,9 @@ Accepted fields:
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 | `dropdownActiveClassDisabled` | `boolean` | `false` | Do not add the link active class when browsing docs. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -513,7 +561,9 @@ If you use docs with versioning, this special navbar item type will link to the
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-docs-version">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -523,7 +573,9 @@ Accepted fields:
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `docsPluginId` | `string` | `'default'` | The ID of the docs plugin that the doc versioning belongs to. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -554,7 +606,9 @@ The user will be able to switch from one locale to another, while staying on the
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="navbar-locale-dropdown">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -563,7 +617,9 @@ Accepted fields:
 | `dropdownItemsBefore` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the beginning of the dropdown. |
 | `dropdownItemsAfter` | <code>[LinkLikeItem](#navbar-dropdown)[]</code> | `[]` | Add additional dropdown items at the end of the dropdown. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -596,7 +652,9 @@ If you use the [search](../../search.md), the search bar will be the rightmost e
 
 However, with this special navbar item type, you can change the default location.
 
+```mdx-code-block
 <APITable name="navbar-search">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -604,7 +662,9 @@ However, with this special navbar item type, you can change the default location
 | `position` | <code>'left' \| 'right'</code> | `'left'` | The side of the navbar this item should appear on. |
 | `className` | `string` | / | Custom CSS class for this navbar item. |
 
+```mdx-code-block
 </APITable>
+```
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -627,7 +687,9 @@ module.exports = {
 
 You can also render your own HTML markup inside a navbar item using this navbar item type.
 
+```mdx-code-block
 <APITable name="navbar-html">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -636,7 +698,9 @@ You can also render your own HTML markup inside a navbar item using this navbar
 | `className` | `string` | `''` | Custom CSS class for this navbar item. |
 | `value` | `string` | `''` | Custom HTML to be rendered inside this navbar item. |
 
+```mdx-code-block
 </APITable>
+```
 
 ```js title="docusaurus.config.js"
 module.exports = {
@@ -694,7 +758,9 @@ Docusaurus uses [Prism React Renderer](https://github.com/FormidableLabs/prism-r
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="codeblock">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -703,7 +769,9 @@ Accepted fields:
 | `defaultLanguage` | `string` | `undefined` | The side of the navbar this item should appear on. |
 | `magicComments` | `MagicCommentConfig[]` | _see below_ | The list of [magic comments](../../guides/markdown-features/markdown-features-code-blocks.mdx#custom-magic-comments). |
 
+```mdx-code-block
 </APITable>
+```
 
 ```ts
 type MagicCommentConfig = {
@@ -771,7 +839,9 @@ You can add logo and a copyright to the footer via `themeConfig.footer`. Logo ca
 
 Accepted fields:
 
+```mdx-code-block
 <APITable name="footer">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -780,7 +850,9 @@ Accepted fields:
 | `style` | <code>'dark' \| 'light'</code> | `'light'` | The color theme of the footer component. |
 | `links` | <code>(Column \| FooterLink)[]</code> | `[]` | The link groups to be present. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 
@@ -790,9 +862,9 @@ module.exports = {
     // highlight-start
     footer: {
       logo: {
-        alt: 'Facebook Open Source Logo',
-        src: 'img/oss_logo.png',
-        href: 'https://opensource.facebook.com',
+        alt: 'Meta Open Source Logo',
+        src: 'img/meta_oss_logo.png',
+        href: 'https://opensource.fb.com',
         width: 160,
         height: 51,
       },
@@ -809,27 +881,35 @@ You can add links to the footer via `themeConfig.footer.links`. There are two ty
 
 Multi-column footer links have a `title` and a list of `FooterItem`s for each column.
 
+```mdx-code-block
 <APITable name="footer-links">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `title` | `string` | `undefined` | Label of the section of these links. |
 | `items` | `FooterItem[]` | `[]` | Links in this section. |
 
+```mdx-code-block
 </APITable>
+```
 
 Accepted fields of each `FooterItem`:
 
+```mdx-code-block
 <APITable name="footer-items">
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `label` | `string` | **Required** | Text to be displayed for this link. |
 | `to` | `string` | **Required** | Client-side routing, used for navigating within the website. The baseUrl will be automatically prepended to this value. |
 | `href` | `string` | **Required** | A full-page navigation, used for navigating outside of the website. **Only one of `to` or `href` should be used.** |
-| `html` | `string` | `undefined` | Renders the html pass-through instead of a simple link. In case `html` is used, no other options should be provided. |
+| `html` | `string` | `undefined` | Renders the HTML pass-through instead of a simple link. In case `html` is used, no other options should be provided. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example multi-column configuration:
 
@@ -919,14 +999,18 @@ module.exports = {
 
 You can adjust the default table of contents via `themeConfig.tableOfContents`.
 
+```mdx-code-block
 <APITable>
+```
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `minHeadingLevel` | `number` | `2` | The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value. |
 | `maxHeadingLevel` | `number` | `3` | Max heading level displayed in the TOC. Should be an integer between 2 and 6. |
 
+```mdx-code-block
 </APITable>
+```
 
 Example configuration:
 

website/versioned_docs/version-2.0.0-rc.1/api/themes/theme-live-codeblock.md

@@ -1,10 +1,10 @@
 ---
 sidebar_position: 3
-id: theme-live-codeblock
-title: '📦 theme-live-codeblock'
-slug: '/api/themes/@docusaurus/theme-live-codeblock'
+slug: /api/themes/@docusaurus/theme-live-codeblock
 ---
 
+# 📦 theme-live-codeblock
+
 This theme provides a `@theme/CodeBlock` component that is powered by react-live. You can read more on [interactive code editor](../../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor) documentation.
 
 ```bash npm2yarn

website/versioned_docs/version-2.0.0-rc.1/api/themes/theme-search-algolia.md

@@ -1,17 +1,17 @@
 ---
 sidebar_position: 4
-id: theme-search-algolia
-title: '📦 theme-search-algolia'
-slug: '/api/themes/@docusaurus/theme-search-algolia'
+slug: /api/themes/@docusaurus/theme-search-algolia
 ---
 
+# 📦 theme-search-algolia
+
 This theme provides a `@theme/SearchBar` component that integrates with Algolia DocSearch easily. Combined with `@docusaurus/theme-classic`, it provides a very easy search integration. You can read more on [search](../../search.md) documentation.
 
 ```bash npm2yarn
 npm install --save @docusaurus/theme-search-algolia
 ```
 
-This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support. You can this default path via `themeConfig.algolia.searchPagePath`. Use `false` to disable search page.
+This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support. You can change this default path via `themeConfig.algolia.searchPagePath`. Use `false` to disable search page.
 
 :::tip
 

website/versioned_docs/version-2.0.0-rc.1/blog.mdx

@@ -1,12 +1,13 @@
 ---
-id: blog
-title: Blog
+description: Deploy a full-featured blog in no time with Docusaurus.
 ---
 
+# Blog
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-The blog feature enables you to deploy in no time a full-featured blog.
+The blog feature enables you to deploy a full-featured blog in no time.
 
 :::info
 
@@ -69,7 +70,7 @@ This is my first post on Docusaurus 2.
 A whole bunch of exploration to follow.
 ```
 
-The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
+The [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter) is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
 
 ## Blog list {#blog-list}
 
@@ -191,9 +192,10 @@ Use the `authors` front matter field to declare blog post authors. An author sho
 
 Blog post authors can be declared directly inside the front matter:
 
-````mdx-code-block
+```mdx-code-block
 <Tabs groupId="author-front-matter">
-  <TabItem value="single" label="Single author">
+<TabItem value="single" label="Single author">
+```
 
 ```md title="my-blog-post.md"
 ---
@@ -206,8 +208,10 @@ authors:
 ---
 ```
 
-  </TabItem>
-  <TabItem value="multiple" label="Multiple authors">
+```mdx-code-block
+</TabItem>
+<TabItem value="multiple" label="Multiple authors">
+```
 
 ```md title="my-blog-post.md"
 ---
@@ -224,9 +228,10 @@ authors:
 ---
 ```
 
-  </TabItem>
+```mdx-code-block
+</TabItem>
 </Tabs>
-````
+```
 
 :::tip
 
@@ -278,9 +283,10 @@ Use the `authorsMapPath` plugin option to configure the path. JSON is also suppo
 
 In blog posts front matter, you can reference the authors declared in the global configuration file:
 
-````mdx-code-block
+```mdx-code-block
 <Tabs groupId="author-front-matter">
-  <TabItem value="single" label="Single author">
+<TabItem value="single" label="Single author">
+```
 
 ```md title="my-blog-post.md"
 ---
@@ -288,8 +294,10 @@ authors: jmarcey
 ---
 ```
 
-  </TabItem>
-  <TabItem value="multiple" label="Multiple authors">
+```mdx-code-block
+</TabItem>
+<TabItem value="multiple" label="Multiple authors">
+```
 
 ```md title="my-blog-post.md"
 ---
@@ -297,9 +305,10 @@ authors: [jmarcey, slorber]
 ---
 ```
 
-  </TabItem>
+```mdx-code-block
+</TabItem>
 </Tabs>
-````
+```
 
 :::info
 
@@ -393,9 +402,10 @@ The default reading time is able to accept additional options: `wordsPerMinute`
 
 Use the callback for all your customization needs:
 
-````mdx-code-block
+```mdx-code-block
 <Tabs>
 <TabItem value="disable-per-post" label="Per-post disabling">
+```
 
 **Disable reading time on one page:**
 
@@ -409,7 +419,9 @@ module.exports = {
           showReadingTime: true,
           // highlight-start
           readingTime: ({content, frontMatter, defaultReadingTime}) =>
-            frontMatter.hide_reading_time ? undefined : defaultReadingTime({content}),
+            frontMatter.hide_reading_time
+              ? undefined
+              : defaultReadingTime({content}),
           // highlight-end
         },
       },
@@ -428,8 +440,10 @@ hide_reading_time: true
 This page will no longer display the reading time stats!
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="passing-options" label="Passing options">
+```
 
 **Pass options to the default reading time function:**
 
@@ -451,8 +465,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="using-custom-algo" label="Using custom algorithms">
+```
 
 **Use a custom implementation of reading time:**
 
@@ -474,9 +490,10 @@ module.exports = {
 };
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
-````
+```
 
 :::
 
@@ -591,7 +608,7 @@ By default, the classic theme assumes only one blog per website and hence includ
 
 Set the `routeBasePath` to the URL route that you want your second blog to be accessed on. Note that the `routeBasePath` here has to be different from the first blog or else there could be a collision of paths! Also, set `path` to the path to the directory containing your second blog's entries.
 
-As documented for [multi-instance plugins](./using-plugins.md#multi-instance-plugins-and-plugin-ids), you need to assign a unique id to the plugins.
+As documented for [multi-instance plugins](./using-plugins.md#multi-instance-plugins-and-plugin-ids), you need to assign a unique ID to the plugins.
 
 ```js title="docusaurus.config.js"
 module.exports = {

website/versioned_docs/version-2.0.0-rc.1/browser-support.md

@@ -1,8 +1,9 @@
 ---
-id: browser-support
-title: Browser support
+description: How to keep a reasonable bundle size while ensuring sufficient browser support.
 ---
 
+# Browser support
+
 Docusaurus allows sites to define the list of supported browsers through a [browserslist configuration](https://github.com/browserslist/browserslist).
 
 ## Purpose {#purpose}
@@ -70,7 +71,7 @@ And browsers used in development are:
 
 - The latest version of Chrome _or_ Firefox _or_ Safari.
 
-You can "evaluate" any config with the `browserslist` cli to obtain the actual list:
+You can "evaluate" any config with the `browserslist` CLI to obtain the actual list:
 
 ```bash
 npx browserslist --env="production"

website/versioned_docs/version-2.0.0-rc.1/cli.md

@@ -1,5 +1,5 @@
 ---
-id: cli
+description: Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.
 ---
 
 # CLI
@@ -41,7 +41,7 @@ Builds and serves a preview of your site locally with [Webpack Dev Server](https
 | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
 | `--hot-only` | `false` | Enables Hot Module Replacement without page refresh as a fallback in case of build failures. More information [here](https://webpack.js.org/configuration/dev-server/#devserverhotonly). |
 | `--no-open` | `false` | Do not open automatically the page in the browser. |
-| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
+| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
 | `--poll [optionalIntervalMs]` | `false` | Use polling of files rather than watching for live reload as a fallback in environments where watching doesn't work. More information [here](https://webpack.js.org/configuration/watch/#watchoptionspoll). |
 | `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
 
@@ -87,13 +87,15 @@ Compiles your site for production.
 | --- | --- | --- |
 | `--bundle-analyzer` | `false` | Analyze your bundle with the [webpack bundle analyzer](https://github.com/webpack-contrib/webpack-bundle-analyzer). |
 | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
-| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
+| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
 | `--no-minify` | `false` | Build website without minimizing JS/CSS bundles. |
 
 :::info
 
 For advanced minification of CSS bundle, we use the [advanced cssnano preset](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-preset-advanced) (along with additional several PostCSS plugins) and [level 2 optimization of clean-css](https://github.com/jakubpawlowicz/clean-css#level-2-optimizations). If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable `USE_SIMPLE_CSS_MINIFIER=true` to minify CSS with the [default cssnano preset](https://github.com/cssnano/cssnano/tree/master/packages/cssnano-preset-default). **Please [fill out an issue](https://github.com/facebook/docusaurus/issues/new?labels=bug%2C+needs+triage&template=bug.md) if you experience CSS minification bugs.**
 
+You can skip the HTML minification with the environment variable `SKIP_HTML_MINIFICATION=true`.
+
 :::
 
 ### `docusaurus swizzle [themeName] [componentName] [siteDir]` {#docusaurus-swizzle}
@@ -137,7 +139,7 @@ Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the
 | --- | --- | --- |
 | `--out-dir` | `build` | The full path for the new output directory, relative to the current workspace. |
 | `--skip-build` | `false` | Deploy website without building it. This may be useful when using a custom deploy script. |
-| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
+| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
 
 ### `docusaurus serve [siteDir]` {#docusaurus-serve-sitedir}
 
@@ -148,7 +150,7 @@ Serve your built website locally.
 | `--port` | `3000` | Use specified port |
 | `--dir` | `build` | The full path for the output directory, relative to the current workspace |
 | `--build` | `false` | Build website before serving |
-| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
+| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
 | `--host` | `localhost` | Specify a host to use. For example, if you want your server to be accessible externally, you can use `--host 0.0.0.0`. |
 | `--no-open` | `false` locally, `true` in CI | Do not open a browser window to the server location. |
 
@@ -168,12 +170,12 @@ By default, the files are written in `website/i18n/<defaultLocale>/...`.
 | --- | --- | --- |
 | `--locale` | `<defaultLocale>` | Define which locale folder you want to write translations the JSON files in |
 | `--override` | `false` | Override existing translation messages |
-| `--config` | `undefined` | Path to docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
+| `--config` | `undefined` | Path to Docusaurus config file, default to `[siteDir]/docusaurus.config.js` |
 | `--messagePrefix` | `''` | Allows adding a prefix to each translation message, to help you highlight untranslated strings |
 
 ### `docusaurus write-heading-ids [siteDir] [files]` {#docusaurus-write-heading-ids-sitedir}
 
-Add [explicit heading ids](./guides/markdown-features/markdown-features-toc.mdx#explicit-ids) to the Markdown documents of your site.
+Add [explicit heading IDs](./guides/markdown-features/markdown-features-toc.mdx#explicit-ids) to the Markdown documents of your site.
 
 | Name | Default | Description |
 | --- | --- | --- |

website/versioned_docs/version-2.0.0-rc.1/configuration.md

@@ -1,8 +1,9 @@
 ---
-id: configuration
-title: Configuration
+description: Configuring your site's behavior through docusaurus.config.js and more.
 ---
 
+# Configuration
+
 import TOCInline from '@theme/TOCInline';
 
 Docusaurus has a unique take on configurations. We encourage you to congregate information about your site into one place. We guard the fields of this file and facilitate making this data object accessible across your site.
@@ -178,4 +179,4 @@ module.exports = {
 };
 ```
 
-Most of the time, this configuration will work just fine. If you want to customize your babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.
+Most of the time, this configuration will work just fine. If you want to customize your Babel configuration (e.g. to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.

website/versioned_docs/version-2.0.0-rc.1/deployment.mdx

@@ -1,8 +1,9 @@
 ---
-id: deployment
-title: Deployment
+description: Deploy your Docusaurus app for production on a range of static site hosting services.
 ---
 
+# Deployment
+
 To build the static files of your website for production, run:
 
 ```bash npm2yarn
@@ -182,8 +183,8 @@ Some Docusaurus sites put the `docs` folder outside of `website` (most likely fo
 
 ```bash
 repo           # git root
-├── docs       # md files
-└── website    # docusaurus root
+├── docs       # MD files
+└── website    # Docusaurus root
 ```
 
 If you decide to use the `website` folder as Netlify's base directory, Netlify will not trigger builds when you update the `docs` folder, and you need to configure a [custom `ignore` command](https://docs.netlify.com/configure-builds/common-configurations/ignore-builds/):
@@ -301,31 +302,37 @@ GitHub enterprise installations should work in the same manner as github.com; yo
 
 Finally, to deploy your site to GitHub Pages, run:
 
-````mdx-code-block
+```mdx-code-block
 <Tabs>
 <TabItem value="bash" label="Bash">
+```
 
 ```bash
 GIT_USER=<GITHUB_USERNAME> yarn deploy
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="windows" label="Windows">
+```
 
 ```batch
 cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
 ```
 
+````mdx-code-block
 </TabItem>
 <TabItem value="powershell" label="PowerShell">
+```mdx-code-block
 
 ```powershell
 cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
-```
+````
 
+```mdx-code-block
 </TabItem>
 </Tabs>
-````
+```
 
 :::caution
 
@@ -351,23 +358,23 @@ Here are two approaches to deploying your docs with GitHub Actions. Based on the
 - Source repo and deployment repo are the **same** repository.
 - The deployment repo is a **remote** repository, different from the source.
 
-````mdx-code-block
+```mdx-code-block
 <Tabs>
 <TabItem value="same" label="Same">
+```
 
 While you can have both jobs defined in the same workflow file, the original `deploy` workflow will always be listed as skipped in the PR check suite status, which is not communicative of the actual status and provides no value to the review process. We therefore propose to manage them as separate workflows instead.
 
 We will use a popular third-party deployment action: [peaceiris/actions-gh-pages](https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus).
 
 <details>
-
 <summary>GitHub action files</summary>
 
 Add these two workflow files:
 
 :::warning Tweak the parameters for your setup
 
-These files assume you are using yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
+These files assume you are using Yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
 
 If your Docusaurus project is not at the root of your repo, you may need to configure a [default working directory](https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#example-set-the-default-shell-and-working-directory), and adjust the paths accordingly.
 
@@ -391,7 +398,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 18
           cache: yarn
 
       - name: Install dependencies
@@ -434,7 +441,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 18
           cache: yarn
 
       - name: Install dependencies
@@ -445,17 +452,20 @@ jobs:
 
 </details>
 
+```mdx-code-block
 </TabItem>
 <TabItem value="remote" label="Remote">
+```
 
 A cross-repo publish is more difficult to set up, because you need to push to another repo with permission checks. We will be using SSH to do the authentication.
 
-1. Generate a new [SSH key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+1. Generate a new [SSH key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent). Since this SSH key will be used in CI, make sure to not enter any passphrase.
 2. By default, your public key should have been created in `~/.ssh/id_rsa.pub`; otherwise, use the name you've provided in the previous step to add your key to [GitHub deploy keys](https://developer.github.com/v3/guides/managing-deploy-keys/).
-3. Copy the key to clipboard with `xclip -sel clip < ~/.ssh/id_rsa.pub` and paste it as a [deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) in your repository. Copy the file content if the command line doesn't work for you. Check the box for `Allow write access` before saving your deployment key.
+3. Copy the key to clipboard with `pbcopy < ~/.ssh/id_rsa.pub` and paste it as a [deploy key](https://developer.github.com/v3/guides/managing-deploy-keys/#deploy-keys) in the deployment repository. Copy the file content if the command line doesn't work for you. Check the box for `Allow write access` before saving your deployment key.
 4. You'll need your private key as a [GitHub secret](https://help.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets) to allow Docusaurus to run the deployment for you.
-5. Copy your private key with `xclip -sel clip < ~/.ssh/id_rsa` and paste a GitHub secret with the name `GH_PAGES_DEPLOY`. Copy the file content if the command line doesn't work for you. Save your secret.
+5. Copy your private key with `pbcopy < ~/.ssh/id_rsa` and paste a GitHub secret with the name `GH_PAGES_DEPLOY` on your source repository. Copy the file content if the command line doesn't work for you. Save your secret.
 6. Create your [documentation workflow file](https://help.github.com/en/actions/configuring-and-managing-workflows/configuring-a-workflow#creating-a-workflow-file) in `.github/workflows/`. In this example it's `deploy.yml`.
+7. You should have essentially: the source repo with the GitHub workflow set with the private SSH key as GitHub Secret and your deployment repo set with the public SSH key in GitHub Deploy Keys.
 
 <details>
 
@@ -465,7 +475,7 @@ A cross-repo publish is more difficult to set up, because you need to push to an
 
 Please make sure that you replace `actions@github.com` with your GitHub email and `gh-actions` with your name.
 
-This file assumes you are using yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
+This file assumes you are using Yarn. If you use npm, change `cache: yarn`, `yarn install --frozen-lockfile`, `yarn build` to `cache: npm`, `npm ci`, `npm run build` accordingly.
 
 :::
 
@@ -486,7 +496,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 18
           cache: yarn
       - name: Install dependencies
         run: yarn install --frozen-lockfile
@@ -499,7 +509,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 16.x
+          node-version: 18
           cache: yarn
       - uses: webfactory/ssh-agent@v0.5.0
         with:
@@ -516,9 +526,24 @@ jobs:
 
 </details>
 
+```mdx-code-block
 </TabItem>
 </Tabs>
-````
+```
+
+<details>
+
+<summary>Site not deployed properly?</summary>
+
+After pushing to main, if you don't see your site published at the desired location (for example, it says "There isn't a GitHub Pages site here", or it's showing your repo's README.md file), check the following:
+
+- It may take a few minutes for GitHub pages to pick up the new files, so wait for about 3 minutes and refresh before concluding it isn't working.
+- On your repo's landing page, you should see a little green tick next to the last commit's title, indicating the CI has passed. If you see a cross, it means the build or deployment failed, and you should check the log for more debugging information.
+- Click on the tick and make sure your see a "Deploy to GitHub Pages" workflow. Names like "pages build and deployment / deploy" are GitHub's default workflows, indicating your custom deployment workflow failed to be triggered at all. Make sure the YAML files are put under the `.github/workflows` folder, and the trigger condition is set correctly (for example, if your default branch is "master" instead of "main", you need to change the `on.push` property).
+- We are using `gh-pages` as the deployment branch. Under your repo's Settings > Pages, make sure the "Source" (which is the source for the _deployment_ files, not "source" as in our terminology) is set to "gh-pages" + "/ (root)".
+- If you are using a custom domain, make sure the DNS record is pointing to the GitHub pages servers' IP.
+
+</details>
 
 ### Triggering deployment with Travis CI {#triggering-deployment-with-travis-ci}
 
@@ -533,7 +558,7 @@ Continuous integration (CI) services are typically used to perform routine tasks
 ```yml title=".travis.yml"
 language: node_js
 node_js:
-  - '14.15.0'
+  - 18
 branches:
   only:
     - main
@@ -575,9 +600,9 @@ After creating this simple pipeline, each new commit pushed to the branch you se
 ### Using Azure Pipelines {#using-azure-pipelines}
 
 1. Sign Up at [Azure Pipelines](https://azure.microsoft.com/en-us/services/devops/pipelines/) if you haven't already.
-2. Create an organization and within the organization create a project and connect your repository from GitHub.
+2. Create an organization. Within the organization, create a project and connect your repository from GitHub.
 3. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/) with the `repo` scope.
-4. In the project page (which looks like `https://dev.azure.com/ORG_NAME/REPO_NAME/_build` create a new pipeline with the following text. Also, click on edit and add a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named `azure-pipelines.yml` at your repository root.
+4. In the project page (which looks like `https://dev.azure.com/ORG_NAME/REPO_NAME/_build`), create a new pipeline with the following text. Also, click on edit and add a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username). Make sure to mark them as secret. Alternatively, you can also add a file named `azure-pipelines.yml` at your repository root.
 
 ```yml title="azure-pipelines.yml"
 trigger:
@@ -592,7 +617,7 @@ steps:
 
   - task: NodeTool@0
     inputs:
-      versionSpec: 14.x
+      versionSpec: '18'
     displayName: Install Node.js
 
   - script: |
@@ -611,8 +636,8 @@ steps:
 
 ### Using Drone {#using-drone}
 
-1. Create a new ssh key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project.
-2. Name your private and public keys to be specific and so that it does not overwrite your other [ssh keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
+1. Create a new SSH key that will be the [deploy key](https://docs.github.com/en/free-pro-team@latest/developers/overview/managing-deploy-keys#deploy-keys) for your project.
+2. Name your private and public keys to be specific and so that it does not overwrite your other [SSH keys](https://docs.github.com/en/free-pro-team@latest/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent).
 3. Go to `https://github.com/USERNAME/REPO/settings/keys` and add a new deploy key by pasting in the public key you just generated.
 4. Open your Drone.io dashboard and log in. The URL looks like `https://cloud.drone.io/USERNAME/REPO`.
 5. Click on the repository, click on activate repository, and add a secret called `git_deploy_private_key` with your private key value that you just generated.

website/versioned_docs/version-2.0.0-rc.1/docusaurus-core.md

@@ -1,9 +1,9 @@
 ---
-id: docusaurus-core
-title: Docusaurus Client API
 sidebar_label: Client API
 ---
 
+# Docusaurus Client API
+
 Docusaurus provides some APIs on the clients that can be helpful to you when building your site.
 
 ## Components {#components}
@@ -479,7 +479,7 @@ Prefer a `require()` call for [assets](./guides/markdown-features/markdown-featu
 
 ### `useBaseUrlUtils` {#useBaseUrlUtils}
 
-Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base url.
+Sometimes `useBaseUrl` is not good enough. This hook return additional utils related to your site's base URL.
 
 - `withBaseUrl`: useful if you need to add base URLs to multiple URLs at once.
 

website/versioned_docs/version-2.0.0-rc.1/guides/creating-pages.md

@@ -1,10 +1,10 @@
 ---
-id: creating-pages
-title: Creating Pages
 slug: /creating-pages
 sidebar_label: Pages
 ---
 
+# Creating Pages
+
 In this section, we will learn about creating pages in Docusaurus.
 
 The `@docusaurus/plugin-content-pages` plugin empowers you to create **one-off standalone pages** like a showcase page, playground page, or support page. You can use React components, or Markdown.

website/versioned_docs/version-2.0.0-rc.1/guides/docs/docs-create-doc.mdx

@@ -0,0 +1,166 @@
+---
+id: create-doc
+description: Create a Markdown Document
+slug: /create-doc
+---
+
+# Create a doc
+
+Create a Markdown file, `greeting.md`, and place it under the `docs` directory.
+
+```bash
+website # root directory of your site
+├── docs
+│   └── greeting.md
+├── src
+│   └── pages
+├── docusaurus.config.js
+├── ...
+```
+
+```md
+---
+description: Create a doc page with rich content.
+---
+
+# Hello from Docusaurus
+
+Are you ready to create the documentation site for your open source project?
+
+## Headers
+
+will show up on the table of contents on the upper right
+
+So that your users will know what this page is all about without scrolling down or even without reading too much.
+
+## Only h2 and h3 will be in the TOC by default.
+
+You can configure the TOC heading levels either per-document or in the theme configuration.
+
+The headers are well-spaced so that the hierarchy is clear.
+
+- lists will help you
+- present the key points
+- that you want your users to remember
+  - and you may nest them
+    - multiple times
+
+## Custom ID headers {#custom-id}
+
+With `{#custom-id}` syntax you can set your own header ID.
+```
+
+:::note
+
+All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.
+
+Read more about [importing partial pages](../markdown-features/markdown-features-react.mdx#importing-markdown).
+
+:::
+
+## Doc front matter {#doc-front-matter}
+
+The [front matter](../markdown-features/markdown-features-intro.mdx#front-matter) is used to provide additional metadata for your doc page. Front matter is optional—Docusaurus will be able to infer all necessary metadata without the front matter. For example, the [doc tags](#dog-tags) feature introduced below requires using front matter. For all possible fields, see [the API documentation](../../api/plugins/plugin-content-docs.md#markdown-front-matter).
+
+## Doc tags {#doc-tags}
+
+Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.md). Tags are passed in the front matter as a list of labels:
+
+```md "your-doc-page.md"
+---
+id: doc-with-tags
+title: A doc with tags
+tags:
+  - Demo
+  - Getting started
+---
+```
+
+:::tip
+
+Tags can also be declared with `tags: [Demo, Getting started]`.
+
+Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).
+
+:::
+
+## Organizing folder structure {#organizing-folder-structure}
+
+How the Markdown files are arranged under the `docs` folder can have multiple impacts on Docusaurus content generation. However, most of them can be decoupled from the file structure.
+
+### Document ID {#document-id}
+
+Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
+
+For example, the ID of `greeting.md` is `greeting`, and the ID of `guide/hello.md` is `guide/hello`.
+
+```bash
+website # Root directory of your site
+└── docs
+   ├── greeting.md
+   └── guide
+      └── hello.md
+```
+
+However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
+
+```md
+---
+id: part1
+---
+
+Lorem ipsum
+```
+
+The ID is used to refer to a document when hand-writing sidebars, or when using docs-related layout components or hooks.
+
+### Doc URLs {#doc-urls}
+
+By default, a document's URL location is its file path relative to the `docs` folder. Use the `slug` front matter to change a document's URL.
+
+For example, suppose your site structure looks like this:
+
+```bash
+website # Root directory of your site
+└── docs
+    └── guide
+        └── hello.md
+```
+
+By default `hello.md` will be available at `/docs/guide/hello`. You can change its URL location to `/docs/bonjour`:
+
+```md
+---
+slug: /bonjour
+---
+
+Lorem ipsum
+```
+
+`slug` will be appended to the doc plugin's `routeBasePath`, which is `/docs` by default. See [Docs-only mode](#docs-only-mode) for how to remove the `/docs` part from the URL.
+
+:::note
+
+It is possible to use:
+
+- absolute slugs: `slug: /mySlug`, `slug: /`...
+- relative slugs: `slug: mySlug`, `slug: ./../mySlug`...
+
+:::
+
+If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter:
+
+```md
+---
+id: my-home-doc
+slug: /
+---
+
+Lorem ipsum
+```
+
+### Sidebars {#sidebars}
+
+When using [autogenerated sidebars](./sidebar/autogenerated.md), the file structure will determine the sidebar structure.
+
+Our recommendation for file system organization is: make your file system mirror the sidebar structure (so you don't need to handwrite your `sidebars.js` file), and use the `slug` front matter to customize URLs of each document.

website/versioned_docs/version-2.0.0-rc.1/guides/docs/docs-introduction.md

@@ -1,10 +1,11 @@
 ---
 id: introduction
-title: Docs Introduction
 sidebar_label: Introduction
 slug: /docs-introduction
 ---
 
+# Docs Introduction
+
 The docs feature provides users with a way to organize Markdown files in a hierarchical format.
 
 :::info
@@ -13,76 +14,14 @@ Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-c
 
 :::
 
-## Document ID {#document-id}
+Your site's documentation is organized by four levels, from lowest to highest:
 
-Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
+1. Individual pages.
+2. Sidebars.
+3. Versions.
+4. Plugin instances.
 
-For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
-
-```bash
-website # Root directory of your site
-└── docs
-   ├── greeting.md
-   └── guide
-      └── hello.md
-```
-
-However, the **last part** of the `id` can be defined by the user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
-
-```md
----
-id: part1
----
-
-Lorem ipsum
-```
-
-### Customizing doc URLs {#customizing-doc-urls}
-
-By default, a document's URL location is its file path relative to the `docs` folder. Use the `slug` front matter to change a document's URL.
-
-For example, suppose your site structure looks like this:
-
-```bash
-website # Root directory of your site
-└── docs
-    └── guide
-        └── hello.md
-```
-
-By default `hello.md` will be available at `/docs/guide/hello`. You can change its URL location to `/docs/bonjour`:
-
-```md
----
-slug: /bonjour
----
-
-Lorem ipsum
-```
-
-`slug` will be appended to the doc plugin's `routeBasePath`, which is `/docs` by default. See [Docs-only mode](#docs-only-mode) for how to remove the `/docs` part from the URL.
-
-:::note
-
-It is possible to use:
-
-- absolute slugs: `slug: /mySlug`, `slug: /`...
-- relative slugs: `slug: mySlug`, `slug: ./../mySlug`...
-
-:::
-
-## Home page docs {#home-page-docs}
-
-If you want a document to be available at the root, and have a path like `https://docusaurus.io/docs/`, you can use the slug front matter:
-
-```md
----
-id: my-home-doc
-slug: /
----
-
-Lorem ipsum
-```
+The guide will introduce them in that order: starting from [how individual pages can be configured](./docs-create-doc.mdx), to [how to create a sidebar or multiple ones](./sidebar/index.md), to [how to create and manage versions](./versioning.md), to [how to use multiple docs plugin instances](./docs-multi-instance.mdx).
 
 ## Docs-only mode {#docs-only-mode}
 

website/versioned_docs/version-2.0.0-rc.1/guides/docs/docs-multi-instance.mdx

@@ -1,10 +1,11 @@
 ---
 id: multi-instance
-title: Docs Multi-instance
 description: Use multiple docs plugin instances on a single Docusaurus site.
 slug: /docs-multi-instance
 ---
 
+# Docs Multi-instance
+
 The `@docusaurus/plugin-content-docs` plugin can support [multi-instance](../../using-plugins.md#multi-instance-plugins-and-plugin-ids).
 
 :::note
@@ -134,7 +135,7 @@ Don't forget to assign a unique `id` attribute to plugin instances.
 
 :::note
 
-We consider that the `product` instance is the most important one, and make it the "default" instance by not assigning any id.
+We consider that the `product` instance is the most important one, and make it the "default" instance by not assigning any ID.
 
 :::
 
@@ -164,7 +165,7 @@ The instance paths will be simpler, and retro-compatible with a single-instance
 
 ## Tagging new versions {#tagging-new-versions}
 
-Each plugin instance will have its own cli command to tag a new version. They will be displayed if you run:
+Each plugin instance will have its own CLI command to tag a new version. They will be displayed if you run:
 
 ```bash npm2yarn
 npm run docusaurus -- --help

website/versioned_docs/version-2.0.0-rc.1/guides/docs/sidebar/autogenerated.md

@@ -411,7 +411,7 @@ By default, Docusaurus will **remove the number prefix** from the doc id, title,
 
 **Prefer using [additional metadata](#autogenerated-sidebar-metadata)**.
 
-Updating a number prefix can be annoying, as it can require **updating multiple existing markdown links**:
+Updating a number prefix can be annoying, as it can require **updating multiple existing Markdown links**:
 
 ```diff title="docs/02-Tutorial Easy/01-First Part.md"
 - Check the [Tutorial End](../04-End.md);

website/versioned_docs/version-2.0.0-rc.1/guides/docs/sidebar/index.md

@@ -198,7 +198,7 @@ A real-world example from the Docusaurus site:
 ```mdx-code-block
 import CodeBlock from '@theme/CodeBlock';
 
-<CodeBlock className="language-js" title="sidebars.js">
+<CodeBlock language="js" title="sidebars.js">
   {require('!!raw-loader!@site/sidebars.js')
     .default
     .split('\n')

website/versioned_docs/version-2.0.0-rc.1/guides/docs/versioning.md

@@ -1,16 +1,16 @@
 ---
-id: versioning
-title: Versioning
 slug: /versioning
 ---
 
+# Versioning
+
+You can use the versioning CLI to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory continues to evolve.
+
 ```mdx-code-block
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 ```
 
-You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
-
 :::caution
 
 Think about it before starting to version your documentation - it can become difficult for contributors to help improve it!
@@ -102,8 +102,10 @@ When tagging a new version, the document versioning mechanism will:
 1. Place the new file into the corresponding version folder.
 2. Include the reference to the new file in the corresponding sidebar file according to the version number.
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Current version structure">
+```
 
 ```bash
 # The new file.
@@ -113,8 +115,10 @@ docs/new.md
 sidebars.js
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="Older version structure">
+```
 
 ```bash
 # The new file.
@@ -124,8 +128,10 @@ versioned_docs/version-1.0.0/new.md
 versioned_sidebars/version-1.0.0-sidebars.json
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```
 
 ### Updating an existing version {#updating-an-existing-version}
 

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-admonitions.mdx

@@ -1,10 +1,11 @@
 ---
 id: admonitions
-title: Admonitions
 description: Handling admonitions/callouts in Docusaurus Markdown
 slug: /markdown-features/admonitions
 ---
 
+# Admonitions
+
 import BrowserWindow from '@site/src/components/BrowserWindow';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -17,68 +18,70 @@ Example:
 ```md
 :::note
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::tip
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::info
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::caution
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::danger
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 ```
 
+```mdx-code-block
 <BrowserWindow>
 
 :::note
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::tip
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::info
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::caution
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 :::danger
 
-Some **content** with _markdown_ `syntax`. Check [this `api`](#).
+Some **content** with _Markdown_ `syntax`. Check [this `api`](#).
 
 :::
 
 </BrowserWindow>
+```
 
 ## Usage with Prettier {#usage-with-prettier}
 
@@ -109,20 +112,22 @@ You may also specify an optional title
 ```md
 :::note Your Title
 
-Some **content** with _markdown_ `syntax`.
+Some **content** with _Markdown_ `syntax`.
 
 :::
 ```
 
+```mdx-code-block
 <BrowserWindow>
 
 :::note Your Title
 
-Some **content** with _markdown_ `syntax`.
+Some **content** with _Markdown_ `syntax`.
 
 :::
 
 </BrowserWindow>
+```
 
 ## Admonitions with MDX {#admonitions-with-mdx}
 
@@ -144,21 +149,21 @@ import TabItem from '@theme/TabItem';
 :::
 ```
 
+```mdx-code-block
 <BrowserWindow>
 
 :::tip Use tabs in admonitions
 
-```mdx-code-block
 <Tabs>
   <TabItem value="apple" label="Apple">This is an apple 🍎</TabItem>
   <TabItem value="orange" label="Orange">This is an orange 🍊</TabItem>
   <TabItem value="banana" label="Banana">This is a banana 🍌</TabItem>
 </Tabs>
-```
 
 :::
 
 </BrowserWindow>
+```
 
 ## Usage in JSX {#usage-in-jsx}
 
@@ -189,6 +194,7 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
 </Admonition>
 ```
 
+```mdx-code-block
 <BrowserWindow>
   <Admonition type="tip" icon="💡" title="Did you know...">
     <p>
@@ -197,3 +203,4 @@ The types that are accepted are the same as above: `note`, `tip`, `danger`, `inf
     </p>
   </Admonition>
 </BrowserWindow>
+```

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-assets.mdx

@@ -1,10 +1,11 @@
 ---
 id: assets
-title: Assets
 description: Handling assets in Docusaurus Markdown
 slug: /markdown-features/assets
 ---
 
+# Assets
+
 import BrowserWindow from '@site/src/components/BrowserWindow';
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -26,8 +27,10 @@ Let's imagine the following file structure:
 
 You can display images in three different ways: Markdown syntax, CJS require, or ES imports syntax.
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Markdown syntax">
+```
 
 Display images using simple Markdown syntax:
 
@@ -35,8 +38,10 @@ Display images using simple Markdown syntax:
 ![Example banner](./assets/docusaurus-asset-example-banner.png)
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="CommonJS require">
+```
 
 Display images using inline CommonJS `require` in JSX image tag:
 
@@ -47,8 +52,10 @@ Display images using inline CommonJS `require` in JSX image tag:
 />
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="Import statement">
+```
 
 Display images using ES `import` syntax and JSX image tag:
 
@@ -58,8 +65,10 @@ import myImageUrl from './assets/docusaurus-asset-example-banner.png';
 <img src={myImageUrl} alt="Example banner" />;
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```
 
 All of the above result in displaying the image:
 
@@ -101,7 +110,7 @@ or
 
 </BrowserWindow>
 
-:::info markdown links are always file paths
+:::info Markdown links are always file paths
 
 If you use the Markdown image or link syntax, all asset paths will be resolved as file paths by Docusaurus and automatically converted to `require()` calls. You don't need to use `require()` in Markdown unless you use the JSX syntax, which you do have to handle yourself.
 

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -1,10 +1,11 @@
 ---
 id: code-blocks
-title: Code blocks
 description: Handling code blocks in Docusaurus Markdown
 slug: /markdown-features/code-blocks
 ---
 
+# Code blocks
+
 import BrowserWindow from '@site/src/components/BrowserWindow';
 import CodeBlock from '@theme/CodeBlock';
 
@@ -22,7 +23,9 @@ function HelloCodeTitle(props) {
 ```
 ````
 
+```mdx-code-block
 <BrowserWindow>
+```
 
 ```jsx title="/src/components/HelloCodeTitle.js"
 function HelloCodeTitle(props) {
@@ -30,7 +33,9 @@ function HelloCodeTitle(props) {
 }
 ```
 
+```mdx-code-block
 </BrowserWindow>
+```
 
 ## Syntax highlighting {#syntax-highlighting}
 
@@ -160,8 +165,9 @@ function HighlightMoreText(highlight) {
 ```
 ````
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
+```
 
 ```js
 function HighlightSomeText(highlight) {
@@ -184,8 +190,9 @@ function HighlightMoreText(highlight) {
 }
 ```
 
+```mdx-code-block
 </BrowserWindow>
-````
+```
 
 Supported commenting syntax:
 
@@ -234,8 +241,9 @@ export default MyComponent;
 ```
 ````
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
+```
 
 ```jsx {1,4-6,11}
 import React from 'react';
@@ -251,8 +259,9 @@ function MyComponent(props) {
 export default MyComponent;
 ```
 
+```mdx-code-block
 </BrowserWindow>
-````
+```
 
 :::tip prefer comments
 
@@ -346,8 +355,9 @@ console.log(name.toUpperCase());
 </Tabs>
 ```
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
+```
 
 In JavaScript, trying to access properties on `null` will error.
 
@@ -358,8 +368,9 @@ console.log(name.toUpperCase());
 // Uncaught TypeError: Cannot read properties of null (reading 'toUpperCase')
 ```
 
+```mdx-code-block
 </BrowserWindow>
-````
+```
 
 If you use number ranges in metastring (the `{1,3-4}` syntax), Docusaurus will apply the **first `magicComments` entry**'s class name. This, by default, is `theme-code-block-highlighted-line`, but if you change the `magicComments` config and use a different entry as the first one, the meaning of the metastring range will change as well.
 
@@ -395,8 +406,9 @@ export default MyComponent;
 ```
 ````
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
+```
 
 ```jsx {1,4-6,11} showLineNumbers
 import React from 'react';
@@ -412,8 +424,9 @@ function MyComponent(props) {
 export default MyComponent;
 ```
 
+```mdx-code-block
 </BrowserWindow>
-````
+```
 
 ## Interactive code editor {#interactive-code-editor}
 
@@ -442,7 +455,7 @@ To use the plugin, create a code block with `live` attached to the language meta
 function Clock(props) {
   const [date, setDate] = useState(new Date());
   useEffect(() => {
-    var timerID = setInterval(() => tick(), 1000);
+    const timerID = setInterval(() => tick(), 1000);
 
     return function cleanup() {
       clearInterval(timerID);
@@ -464,14 +477,15 @@ function Clock(props) {
 
 The code block will be rendered as an interactive editor. Changes to the code will reflect on the result panel live.
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
+```
 
 ```jsx live
 function Clock(props) {
   const [date, setDate] = useState(new Date());
   useEffect(() => {
-    var timerID = setInterval(() => tick(), 1000);
+    const timerID = setInterval(() => tick(), 1000);
 
     return function cleanup() {
       clearInterval(timerID);
@@ -490,8 +504,9 @@ function Clock(props) {
 }
 ```
 
+```mdx-code-block
 </BrowserWindow>
-````
+```
 
 ### Imports {#imports}
 
@@ -504,7 +519,7 @@ It is not possible to import components directly from the react-live code editor
 By default, all React imports are available. If you need more imports available, swizzle the react-live scope:
 
 ```bash npm2yarn
-npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope
+npm run swizzle @docusaurus/theme-live-codeblock ReactLiveScope -- --eject
 ```
 
 ```jsx title="src/theme/ReactLiveScope/index.js"
@@ -540,8 +555,9 @@ export default ReactLiveScope;
 
 The `ButtonExample` component is now available to use:
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
+```
 
 ```jsx live
 function MyPlayground(props) {
@@ -553,6 +569,43 @@ function MyPlayground(props) {
 }
 ```
 
+```mdx-code-block
+</BrowserWindow>
+```
+
+### Imperative Rendering (noInline)
+
+The `noInline` option should be used to avoid errors when your code spans multiple components or variables.
+
+````md
+```jsx live noInline
+const project = 'Docusaurus';
+
+const Greeting = () => <p>Hello {project}!</p>;
+
+render(<Greeting />);
+```
+````
+
+Unlike an ordinary interactive code block, when using `noInline` React Live won't wrap your code in an inline function to render it.
+
+You will need to explicitly call `render()` at the end of your code to display the output.
+
+````mdx-code-block
+<BrowserWindow>
+
+```jsx live noInline
+const project = "Docusaurus";
+
+const Greeting = () => (
+  <p>Hello {project}!</p>
+);
+
+render(
+  <Greeting />
+);
+```
+
 </BrowserWindow>
 ````
 
@@ -645,10 +698,11 @@ class HelloWorld {
 
 And you will get the following:
 
-````mdx-code-block
+```mdx-code-block
 <BrowserWindow>
 <Tabs>
 <TabItem value="js" label="JavaScript">
+```
 
 ```js
 function helloWorld() {
@@ -656,16 +710,20 @@ function helloWorld() {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="py" label="Python">
+```
 
 ```py
 def hello_world():
   print("Hello, world!")
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="java" label="Java">
+```
 
 ```java
 class HelloWorld {
@@ -675,10 +733,11 @@ class HelloWorld {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
 </BrowserWindow>
-````
+```
 
 If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](markdown-features-tabs.mdx#syncing-tab-choices).
 
@@ -754,6 +813,7 @@ export default function MyReactPage() {
 }
 ```
 
+```mdx-code-block
 <BrowserWindow>
   <CodeBlock
     language="jsx"
@@ -764,6 +824,7 @@ export default function MyReactPage() {
 }`}
   </CodeBlock>
 </BrowserWindow>
+```
 
 The props accepted are `language`, `title` and `showLineNumbers`, in the same way as you write Markdown code blocks.
 

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-head-metadata.mdx

@@ -1,6 +1,5 @@
 ---
 id: head-metadata
-title: Head Metadata
 description: Declaring page-specific head metadata through MDX
 slug: /markdown-features/head-metadata
 ---

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-intro.mdx

@@ -1,11 +1,11 @@
 ---
 id: introduction
-title: Markdown Features
-sidebar_label: Introduction
 description: Docusaurus uses MDX. Find out more about Docusaurus-specific features when writing Markdown.
 slug: /markdown-features
 ---
 
+# Markdown Features
+
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
 Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
@@ -56,6 +56,22 @@ In general, you should only assume the _semantics_ of the markup (` ``` ` fences
 
 </details>
 
+## Front matter {#front-matter}
+
+Front matter is used to add metadata to your Markdown file. All content plugins have their own front matter schema, and use the front matter to enrich the default metadata inferred from the content or other configuration.
+
+Front matter is provided at the very top of the file, enclosed by three dashes `---`. The content is parsed as [YAML](https://yaml.org/spec/1.2.2/).
+
+```md
+---
+title: My Doc Title
+more_data:
+  - Can be provided
+  - as: objects
+    or: arrays
+---
+```
+
 ## Quotes {#quotes}
 
 Markdown quotes are beautifully styled:

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-math-equations.mdx

@@ -1,10 +1,11 @@
 ---
 id: math-equations
-title: Math Equations
 description: Writing LaTeX Math Equations
 slug: /markdown-features/math-equations
 ---
 
+# Math Equations
+
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
 Mathematical equations can be rendered using [KaTeX](https://katex.org).
@@ -131,7 +132,7 @@ module.exports = {
 
 ## Self-hosting KaTeX assets {#self-hosting-katex-assets}
 
-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`).
+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 = {

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-plugins.mdx

@@ -1,10 +1,11 @@
 ---
 id: plugins
-title: MDX Plugins
 description: Using MDX plugins to expand Docusaurus Markdown functionalities
 slug: /markdown-features/plugins
 ---
 
+# MDX Plugins
+
 Sometimes, you may want to extend or tweak your Markdown syntax. For example:
 
 - How do I embed youtube videos using the image syntax (`![](https://youtu.be/yKNxeF4KMsY)`)?

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-react.mdx

@@ -1,6 +1,5 @@
 ---
 id: react
-title: MDX and React
 description: Using the power of React in Docusaurus Markdown documents, thanks to MDX
 slug: /markdown-features/react
 ---
@@ -201,25 +200,53 @@ We use lower-case tag names like `highlight` to "pretend" that they are intrinsi
 
 :::
 
+:::caution
+
+This feature is powered by [a wrapper provider](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/advanced/components#mdxprovider). If you are importing Markdown in a React page, you have to supply this provider yourself through the `MDXContent` theme component.
+
+```jsx title="src/pages/index.js"
+import React from 'react';
+import FeatureDisplay from './_featureDisplay.mdx';
+// highlight-next-line
+import MDXContent from '@theme/MDXContent';
+
+export default function LandingPage() {
+  return (
+    <div>
+      {/* highlight-start */}
+      <MDXContent>
+        <FeatureDisplay />
+      </MDXContent>
+      {/* highlight-end */}
+    </div>
+  );
+}
+```
+
+If you don't wrap your imported MDX with `MDXContent`, the global scope will not be available.
+
+:::
+
 ### Markdown and JSX interoperability {#markdown-and-jsx-interoperability}
 
 Docusaurus v2 is using MDX v1, which has a lot of known cases where the content fails to be correctly parsed as Markdown. Use the **[MDX playground](https://mdx-git-renovate-babel-monorepo-mdx.vercel.app/playground)** to ensure that your syntax is valid MDX.
 
-````mdx-code-block
 <details>
-
 <summary>Samples of parsing failures</summary>
 
 **A paragraph starting with a JSX tag will be seen entirely as a JSX string:**
 
+```mdx-code-block
 <Tabs groupId="jsx-and-md">
 <TabItem value="Problem">
 <div className={styles.wrappingBlock}>
+```
 
 ```jsx
 <span style={{color: 'red'}}>Highlighted text</span> but afterwards _Markdown_ **doesn't work**
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -234,6 +261,7 @@ Docusaurus v2 is using MDX v1, which has a lot of known cases where the content
 Use JSX for the rest of the line, or prefix the line with some plain text:
 
 <div className={styles.wrappingBlock}>
+```
 
 ```jsx
 <span style={{color: 'red'}}>Use JSX for the paragraph</span> to stop <i>worrying about</i> <b>Markdown</b>
@@ -241,6 +269,7 @@ Use JSX for the rest of the line, or prefix the line with some plain text:
 &#8203;<span style={{color: 'red'}}>← This is a zero-width space</span> and afterwards <i>Markdown</i> <b>works</b>
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -259,11 +288,13 @@ Use JSX for the rest of the line, or prefix the line with some plain text:
 <Tabs groupId="jsx-and-md">
 <TabItem value="Problem">
 <div className={styles.wrappingBlock}>
+```
 
 ```jsx
 <span style={{color: 'red'}}>**Bold doesn't work**</span>
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -279,6 +310,7 @@ Use JSX for the rest of the line, or prefix the line with some plain text:
 Use JSX within JSX tag, or move the Markdown to the outer layer:
 
 <div className={styles.wrappingBlock}>
+```
 
 ```jsx
 <span style={{color: 'red'}}><b>Bold now works</b></span>
@@ -286,6 +318,7 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
 **<span style={{color: 'red'}}>Bold now works</span>**
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -304,13 +337,16 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
 <Tabs groupId="jsx-and-md">
 <TabItem value="Problem">
 <div className={styles.wrappingBlock}>
+```
 
+<!-- prettier-ignore -->
 ```jsx
 <div style={{color: 'red'}}>
 **Bold still doesn't work**
 </div>
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -327,7 +363,9 @@ Use JSX within JSX tag, or move the Markdown to the outer layer:
 Add an empty new line:
 
 <div className={styles.wrappingBlock}>
+```
 
+<!-- prettier-ignore -->
 ```jsx
 <div style={{color: 'red'}}>
 
@@ -336,6 +374,7 @@ Add an empty new line:
 </div>
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -354,7 +393,9 @@ Add an empty new line:
 <Tabs groupId="jsx-and-md">
 <TabItem value="Problem">
 <div className={styles.wrappingBlock}>
+```
 
+<!-- prettier-ignore -->
 ```jsx
 <div style={{color: 'red'}}>
 
@@ -363,6 +404,7 @@ Add an empty new line:
 </div>
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -381,7 +423,9 @@ Add an empty new line:
 Don't indent:
 
 <div className={styles.wrappingBlock}>
+```
 
+<!-- prettier-ignore -->
 ```jsx
 <div style={{color: 'red'}}>
 
@@ -390,6 +434,7 @@ Now I'm actually just text
 </div>
 ```
 
+```mdx-code-block
 </div>
 <div className={styles.wrappingBlock}>
 <BrowserWindow>
@@ -402,8 +447,9 @@ Now I'm actually just text
 </div>
 </TabItem>
 </Tabs>
+```
+
 </details>
-````
 
 ## Importing code snippets {#importing-code-snippets}
 
@@ -453,7 +499,7 @@ This feature is experimental and might be subject to breaking API changes in the
 
 You can use Markdown files as components and import them elsewhere, either in Markdown files or in React pages.
 
-By convention, using the **`_` filename prefix** will not create any doc page and means the markdown file is a **"partial"**, to be imported by other files.
+By convention, using the **`_` filename prefix** will not create any doc page and means the Markdown file is a **"partial"**, to be imported by other files.
 
 ```md title="_markdown-partial-example.mdx"
 <span>Hello {props.name}</span>

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-tabs.mdx

@@ -1,10 +1,11 @@
 ---
 id: tabs
-title: Tabs
 description: Using tabs inside Docusaurus Markdown
 slug: /markdown-features/tabs
 ---
 
+# Tabs
+
 ```mdx-code-block
 import BrowserWindow from '@site/src/components/BrowserWindow';
 import Tabs from '@theme/Tabs';

website/versioned_docs/version-2.0.0-rc.1/guides/markdown-features/markdown-features-toc.mdx

@@ -34,7 +34,7 @@ Each heading has an ID that can be automatically generated or explicitly specifi
 <Link to="#heading-id">link</Link>
 ```
 
-By default, Docusaurus will generate heading IDs for you, based on the heading text. For example, `### Hello World` will have id `hello-world`.
+By default, Docusaurus will generate heading IDs for you, based on the heading text. For example, `### Hello World` will have ID `hello-world`.
 
 Generated IDs have **some limitations**:
 
@@ -49,7 +49,7 @@ A special Markdown syntax lets you set an **explicit heading id**:
 
 :::tip
 
-Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit ids to all your Markdown documents.
+Use the **[write-heading-ids](../../cli.md#docusaurus-write-heading-ids-sitedir)** CLI command to add explicit IDs to all your Markdown documents.
 
 :::
 
@@ -61,7 +61,7 @@ Generated heading IDs will be guaranteed to be unique on each page, but if you u
 
 ## Inline table of contents {#inline-table-of-contents}
 
-Each Markdown document displays a table of contents on the top-right corner. But it is also possible to display an inline table of contents directly inside a markdown document, thanks to MDX.
+Each Markdown document displays a table of contents on the top-right corner. But it is also possible to display an inline table of contents directly inside a Markdown document, thanks to MDX.
 
 The `toc` variable is available in any MDX document and contains all the headings of an MDX document. By default, only `h2` and `h3` headings are displayed in the TOC. You can change which heading levels are visible by setting `minHeadingLevel` or `maxHeadingLevel` for individual `TOCInline` components.
 
@@ -121,7 +121,7 @@ The table-of-contents is generated by parsing the Markdown source with a [Remark
 
 Markdown headings within hideable areas will still show up in the TOC. For example, headings within [`Tabs`](./markdown-features-tabs.mdx) and [`details`](./markdown-features-intro.mdx#details) will not be excluded.
 
-Non-markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue.
+Non-Markdown headings will not show up in the TOC. This can be used to your advantage to tackle the aforementioned issue.
 
 ```md
 <details>

website/versioned_docs/version-2.0.0-rc.1/i18n/i18n-crowdin.mdx

@@ -1,10 +1,11 @@
 ---
 id: crowdin
-title: i18n - Using Crowdin
 slug: /i18n/crowdin
 toc_max_heading_level: 4
 ---
 
+# i18n - Using Crowdin
+
 The i18n system of Docusaurus is **decoupled from any translation software**.
 
 You can integrate Docusaurus with the **tools and SaaS of your choice**, as long as you put the **translation files at the correct location**.
@@ -443,7 +444,7 @@ Crowdin has an [In-Context localization](https://support.crowdin.com/in-context-
 
 Unfortunately, it does not work yet for technical reasons, but we have good hope it can be solved.
 
-Crowdin replaces markdown strings with technical ids such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and messes up with front matter, admonitions, JSX...
+Crowdin replaces Markdown strings with technical IDs such as `crowdin:id12345`, but it does so too aggressively, including hidden strings, and messes up with front matter, admonitions, JSX...
 
 :::
 

website/versioned_docs/version-2.0.0-rc.1/i18n/i18n-git.md

@@ -1,9 +1,10 @@
 ---
 id: git
-title: i18n - Using git
 slug: /i18n/git
 ---
 
+# i18n - Using git
+
 A **possible translation strategy** is to **version control the translation files** with Git (or any other [VCS](https://en.wikipedia.org/wiki/Version_control)).
 
 ## Tradeoffs {#tradeoffs}

website/versioned_docs/version-2.0.0-rc.1/i18n/i18n-introduction.md

@@ -1,9 +1,10 @@
 ---
 id: introduction
-title: i18n - Introduction
 slug: /i18n/introduction
 ---
 
+# i18n - Introduction
+
 It is **easy to translate a Docusaurus website** with its internationalization ([i18n](https://en.wikipedia.org/wiki/Internationalization_and_localization)) support.
 
 ## Goals {#goals}

website/versioned_docs/version-2.0.0-rc.1/i18n/i18n-tutorial.md

@@ -1,9 +1,11 @@
 ---
 id: tutorial
-title: i18n - Tutorial
+description: This tutorial will walk you through the basics of the Docusaurus i18n system.
 slug: /i18n/tutorial
 ---
 
+# i18n - Tutorial
+
 ```mdx-code-block
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -113,8 +115,10 @@ Locate all text labels in your React code that will be visible to your users, an
 
 Use the one that better fits the context semantically. For example, the `<Translate>` can be used as React children, while for props that expect a string, the callback can be used.
 
+```mdx-code-block
 <Tabs>
 <TabItem value="Before">
+```
 
 ```jsx title="src/pages/index.js"
 import React from 'react';
@@ -142,8 +146,10 @@ export default function Home() {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="After">
+```
 
 ```jsx title="src/pages/index.js"
 import React from 'react';
@@ -197,8 +203,10 @@ export default function Home() {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
+```
 
 :::info
 
@@ -412,18 +420,18 @@ We only copy `.md` and `.mdx` files, as React pages are translated through JSON
 
 :::
 
-:::tip Use explicit heading ids
+:::tip Use explicit heading IDs
 
-By default, a Markdown heading `### Hello World` will have a generated id `hello-world`. Other documents can link it with `[link](#hello-world)`. However, after translation, the heading becomes `### Bonjour le Monde`, with id `bonjour-le-monde`.
+By default, a Markdown heading `### Hello World` will have a generated ID `hello-world`. Other documents can link it with `[link](#hello-world)`. However, after translation, the heading becomes `### Bonjour le Monde`, with ID `bonjour-le-monde`.
 
-Generated ids are not always a good fit for localized sites, as it requires you to localize all the anchor links:
+Generated IDs are not always a good fit for localized sites, as it requires you to localize all the anchor links:
 
 ```diff
 - [link](#hello-world).
 + [link](#bonjour-le-monde)
 ```
 
-For localized sites, it is recommended to use **[explicit heading ids](../guides/markdown-features/markdown-features-toc.mdx#explicit-ids)**.
+For localized sites, it is recommended to use **[explicit heading IDs](../guides/markdown-features/markdown-features-toc.mdx#explicit-ids)**.
 
 :::
 

website/versioned_docs/version-2.0.0-rc.1/installation.md

@@ -1,8 +1,9 @@
 ---
-id: installation
-title: Installation
+description: How to install Docusaurus locally, and start a Docusaurus site in no time.
 ---
 
+# Installation
+
 ```mdx-code-block
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';

website/versioned_docs/version-2.0.0-rc.1/introduction.md

@@ -1,10 +1,10 @@
 ---
-id: introduction
-title: Introduction
 description: Docusaurus was designed from the ground up to be easily installed and used to get your website up and running quickly.
 slug: /
 ---
 
+# Introduction
+
 ⚡️ Docusaurus will help you ship a **beautiful documentation site in no time**.
 
 💸 Building a custom tech stack is expensive. Instead, **focus on your content** and just write Markdown files.
@@ -108,7 +108,7 @@ Our shared goal—to help your users quickly find what they need and understand
   - HTML files are statically generated for every possible path.
   - Page-specific SEO to help your users land on your official docs directly relating their problems at hand.
 - 📝 **Powered by MDX**:
-  - Write interactive components via JSX and React embedded in markdown.
+  - Write interactive components via JSX and React embedded in Markdown.
   - Share your code in live editors to get your users to love your products on the spot.
 - 🔍 **Search**: Your full site is searchable.
 - 💾 **Document Versioning**: Helps you keep documentation in sync with project releases.

website/versioned_docs/version-2.0.0-rc.1/migration/migration-automated.md

@@ -1,9 +1,9 @@
 ---
-id: migration-automated
-title: Automated migration
 slug: /migration/automated
 ---
 
+# Automated migration
+
 The migration CLI automatically migrates your v1 website to a v2 website.
 
 :::info

website/versioned_docs/version-2.0.0-rc.1/migration/migration-manual.md

@@ -1,10 +1,10 @@
 ---
-id: migration-manual
-title: Manual migration
 slug: /migration/manual
 toc_max_heading_level: 4
 ---
 
+# Manual migration
+
 This manual migration process should be run after the [automated migration process](./migration-automated.md), to complete the missing parts, or debug issues in the migration CLI output.
 
 ## Project setup {#project-setup}
@@ -15,7 +15,7 @@ This manual migration process should be run after the [automated migration proce
 
 In Docusaurus 2, we use scoped package names:
 
-- `docusaurus` -> `@docusaurus/core`
+- `docusaurus` → `@docusaurus/core`
 
 This provides a clear distinction between Docusaurus' official packages and community maintained packages. In another words, all Docusaurus' official packages are namespaced under `@docusaurus/`.
 
@@ -223,8 +223,8 @@ module.exports = {
   themeConfig: {
     footer: {
       logo: {
-        alt: 'Facebook Open Source Logo',
-        src: 'https://docusaurus.io/img/oss_logo.png',
+        alt: 'Meta Open Source Logo',
+        src: '/img/meta_oss_logo.png',
         href: 'https://opensource.facebook.com/',
       },
       copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`, // You can also put own HTML here.
@@ -418,8 +418,8 @@ The following fields are all deprecated, you may remove from your configuration
 - `facebookPixelId`
 - `fonts`
 - `highlight` - We now use [Prism](https://prismjs.com/) instead of [highlight.js](https://highlightjs.org/).
-- `markdownOptions` - We use MDX in v2 instead of Remarkable. Your markdown options have to be converted to Remark/Rehype plugins.
-- `markdownPlugins` - We use MDX in v2 instead of Remarkable. Your markdown plugins have to be converted to Remark/Rehype plugins.
+- `markdownOptions` - We use MDX in v2 instead of Remarkable. Your Markdown options have to be converted to Remark/Rehype plugins.
+- `markdownPlugins` - We use MDX in v2 instead of Remarkable. Your Markdown plugins have to be converted to Remark/Rehype plugins.
 - `manifest`
 - `onPageNav` - This is turned on by default now.
 - `separateCss` - It can imported in the same manner as `custom.css` mentioned above.
@@ -470,13 +470,13 @@ module.exports = {
 };
 ```
 
-If you want to keep the `.html` extension as the canonical url of a page, docs can declare a `slug: installation.html` front matter.
+If you want to keep the `.html` extension as the canonical URL of a page, docs can declare a `slug: installation.html` front matter.
 
 ## Components {#components}
 
 ### 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.md) 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.md) other than document.
 
 You'll have to migrate your sidebar if it contains category type. Rename `subcategory` to `category` and `ids` to `items`.
 
@@ -507,8 +507,8 @@ module.exports = {
   themeConfig: {
     footer: {
       logo: {
-        alt: 'Facebook Open Source Logo',
-        src: 'img/oss_logo.png',
+        alt: 'Meta Open Source Logo',
+        src: '/img/meta_oss_logo.png',
         href: 'https://opensource.facebook.com',
       },
     },
@@ -577,9 +577,9 @@ This feature is replaced by [inline table of content](../guides/markdown-feature
 
 ### Update Markdown syntax to be MDX-compatible {#update-markdown-syntax-to-be-mdx-compatible}
 
-In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like `<img>` and `<br>` which are valid in HTML would have to be explicitly closed now ( `<img/>` and `<br/>`). All tags in MDX documents have to be valid JSX.
+In Docusaurus 2, the Markdown syntax has been changed to [MDX](https://mdxjs.com/). Hence there might be some broken syntax in the existing docs which you would have to update. A common example is self-closing tags like `<img>` and `<br>` which are valid in HTML would have to be explicitly closed now ( `<img/>` and `<br/>`). All tags in MDX documents have to be valid JSX.
 
-Front matter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your front matter use special characters like `:`, you now need to quote it: `title: Part 1: my part1 title` -> `title: Part 1: "my part1 title"`.
+Front matter is parsed by [gray-matter](https://github.com/jonschlinkert/gray-matter). If your front matter use special characters like `:`, you now need to quote it: `title: Part 1: my part1 title` → `title: "Part 1: my part1 title"`.
 
 **Tips**: You might want to use some online tools like [HTML to JSX](https://transform.tools/html-to-jsx) to make the migration easier.
 

website/versioned_docs/version-2.0.0-rc.1/migration/migration-overview.md

@@ -1,12 +1,12 @@
 ---
-id: migration-overview
-title: Migration overview
 slug: /migration
 ---
 
+# Migration overview
+
 This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
 
-We try to make this as easy as possible, and provide a migration cli.
+We try to make this as easy as possible, and provide a migration CLI.
 
 ## Main differences {#main-differences}
 
@@ -66,9 +66,9 @@ You are free to put the `/docs` folder anywhere you want after having migrated t
 There are multiple things to migrate to obtain a fully functional Docusaurus 2 website:
 
 - packages
-- cli commands
+- CLI commands
 - site configuration
-- markdown files
+- Markdown files
 - sidebars file
 - pages, components and CSS
 - versioned docs
@@ -76,13 +76,13 @@ There are multiple things to migrate to obtain a fully functional Docusaurus 2 w
 
 ## Automated migration process {#automated-migration-process}
 
-The [migration cli](./migration-automated.md) will handle many things of the migration for you.
+The [migration CLI](./migration-automated.md) will handle many things of the migration for you.
 
 However, some parts can't easily be automated, and you will have to fallback to the manual process.
 
 :::note
 
-We recommend running the migration cli, and complete the missing parts thanks to the manual migration process.
+We recommend running the migration CLI, and complete the missing parts thanks to the manual migration process.
 
 :::
 

website/versioned_docs/version-2.0.0-rc.1/migration/migration-translated-sites.md

@@ -1,9 +1,9 @@
 ---
-id: migration-translated-sites
-title: Translated sites
 slug: /migration/translated-sites
 ---
 
+# Translated sites
+
 This page explains how migrate a translated Docusaurus v1 site to Docusaurus v2.
 
 ## i18n differences {#i18n-differences}
@@ -110,21 +110,21 @@ Unfortunately, Crowdin does not have any "Duplicate/clone Project" feature, whic
 - Download the Crowdin translations locally
 - Try to run/build your site and see if there are any errors
 
-You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated md files might be invalid for the MDX parser.
+You will likely have errors on your first-try: the pre-translation might try to translate things that it should not be translated (front matter, admonition, code blocks...), and the translated MD files might be invalid for the MDX parser.
 
-You will have to fix all the errors until your site builds. You can do that by modifying the translated md files locally, and fix your site for one locale at a time using `docusaurus build --locale fr`.
+You will have to fix all the errors until your site builds. You can do that by modifying the translated MD files locally, and fix your site for one locale at a time using `docusaurus build --locale fr`.
 
 There is no ultimate guide we could write to fix these errors, but common errors are due to:
 
 - Not marking enough strings as "hidden strings" in Crowdin, leading to pre-translation trying to translate these strings.
-- Having bad v1 translations, leading to invalid markup in v2: bad html elements inside translations and unclosed tags
+- Having bad v1 translations, leading to invalid markup in v2: bad HTML elements inside translations and unclosed tags
 - Anything rejected by the MDX parser, like using HTML elements instead of JSX elements (use the [MDX playground](https://mdxjs.com/playground/) for debugging)
 
 You might want to repeat this pre-translation process, eventually trying the "Perfect" option and limiting pre-translation only some languages/files.
 
 :::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.
 
 :::
 
@@ -136,7 +136,7 @@ The Crowdin Markdown parser is evolving other time and each Crowdin project has
 
 This parser version is undocumented, and you will have to ask the Crowdin support to know your project's parser version and fix one specific version.
 
-Using the same cli version and parser version across the 2 Crowdin projects might give better results.
+Using the same CLI version and parser version across the 2 Crowdin projects might give better results.
 
 :::
 

website/versioned_docs/version-2.0.0-rc.1/migration/migration-versioned-sites.md

@@ -1,9 +1,9 @@
 ---
-id: migration-versioned-sites
-title: Versioned sites
 slug: /migration/versioned-sites
 ---
 
+# Versioned sites
+
 Read up https://docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
 
 :::note
@@ -14,7 +14,7 @@ The versioned docs should normally be migrated correctly by the [migration CLI](
 
 ## Migrate your `versioned_docs` front matter {#migrate-your-versioned_docs-front-matter}
 
-Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation.
+Unlike v1, The Markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual ID field. See scenario below for better explanation.
 
 For example, if you have a `docs/hello.md`.
 
@@ -66,9 +66,9 @@ Hi, Endilie here :)
 
 ## Migrate your `versioned_sidebars` {#migrate-your-versioned_sidebars}
 
-- Refer to `versioned_docs` id as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
+- Refer to `versioned_docs` ID as `version-${version}/${id}` (v2) instead of `version-${version}-${original_id}` (v1).
 
-Because in v1 there is a good chance someone created a new file with front matter id `"version-${version}-${id}"` that can conflict with `versioned_docs` id.
+Because in v1 there is a good chance someone created a new file with front matter ID `"version-${version}-${id}"` that can conflict with `versioned_docs` ID.
 
 For example, Docusaurus 1 can't differentiate `docs/xxx.md`
 
@@ -139,7 +139,7 @@ website
 │   └── version-1.0.0-sidebars.json
 ```
 
-In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right front matter and id reference too).
+In v2, you have to populate the missing `versioned_docs` and `versioned_sidebars` (with the right front matter and ID reference too).
 
 ```bash {3-5,12}
 website

website/versioned_docs/version-2.0.0-rc.1/search.md

@@ -1,10 +1,11 @@
 ---
-title: Search
 keywords:
   - algolia
   - search
 ---
 
+# Search
+
 There are a few options you can use to add search to your website:
 
 - 🥇 [Algolia DocSearch](#using-algolia-docsearch) (**official**)

website/versioned_docs/version-2.0.0-rc.1/seo.md

@@ -1,12 +1,13 @@
 ---
-id: seo
-title: Search engine optimization (SEO)
+description: How to make your Docusaurus site maximally search-engine-friendly.
 sidebar_label: SEO
 keywords:
   - seo
   - positioning
 ---
 
+# Search engine optimization (SEO)
+
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
 Docusaurus supports search engine optimization in a variety of ways.

website/versioned_docs/version-2.0.0-rc.1/static-assets.md

@@ -1,11 +1,12 @@
 ---
-id: static-assets
-title: Static Assets
+description: Static assets are the non-code files that are directly copied to the build output. Learn about how they are handled and what the best practices of using static assets are.
 ---
 
-Every website needs assets: images, stylesheets, favicons, etc. By default, you are suggested to put these assets in the `static` folder.
+# Static Assets
 
-Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`.
+Static assets are the non-code files that are directly copied to the build output. They include images, stylesheets, favicons, fonts, etc.
+
+By default, you are suggested to put these assets in the `static` folder. Every file you put into **that directory will be copied** into the root of the generated `build` folder with the directory hierarchy preserved. E.g. if you add a file named `sun.jpg` to the static folder, it will be copied to `build/sun.jpg`.
 
 This means that:
 
@@ -68,7 +69,7 @@ You write a link like this: [Download this document](/files/note.docx)
 Docusaurus changes that to: <a href={require('static/files/note.docx')}>Download this document</a>
 ```
 
-:::caution use markdown syntax
+:::caution use Markdown syntax
 
 Docusaurus will only parse links that are in Markdown syntax. If your asset references are using the JSX tag `<a>` / `<img>`, nothing will be done.
 

website/versioned_docs/version-2.0.0-rc.1/styling-layout.md

@@ -1,11 +1,11 @@
 ---
-id: styling-layout
-title: Styling and Layout
 description: A Docusaurus site is a pre-rendered single-page React application. You can style it the way you style React apps.
 ---
 
 import ColorGenerator from '@site/src/components/ColorGenerator';
 
+# Styling and Layout
+
 :::tip
 
 This section is focused on styling through stylesheets. For more advanced customizations (DOM structure, React code...), refer to the [swizzling guide](./swizzling.md).

website/versioned_docs/version-2.0.0-rc.1/swizzling.md

@@ -41,9 +41,10 @@ npm run swizzle
 
 It will generate a new component your `src/theme` directory, which should look like this example:
 
-````mdx-code-block
+```mdx-code-block
 <Tabs>
 <TabItem value="Ejecting">
+```
 
 ```jsx title="src/theme/SomeComponent.js"
 import React from 'react';
@@ -60,8 +61,10 @@ export default function SomeComponent(props) {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 <TabItem value="Wrapping">
+```
 
 ```jsx title="src/theme/SomeComponent.js"
 import React from 'react';
@@ -78,9 +81,10 @@ export default function SomeComponentWrapper(props) {
 }
 ```
 
+```mdx-code-block
 </TabItem>
 </Tabs>
-````
+```
 
 To get an overview of all the themes and components available to swizzle, run:
 
@@ -237,7 +241,7 @@ Moreover, internal components may simply disappear. If a component is called `Si
 For each theme component, the swizzle CLI will indicate **3 different levels of safety** declared by theme authors:
 
 - **Safe**: this component is safe to be swizzled, its public API is considered stable, and no breaking changes should happen within a theme **major version**
-- **Unsafe**: this component is a theme implementation detail, not safe to be swizzled, and breaking changes might happen withing a theme **minor version**
+- **Unsafe**: this component is a theme implementation detail, not safe to be swizzled, and breaking changes might happen within a theme **minor version**
 - **Forbidden**: the swizzle CLI will prevent you from swizzling this component, because it is not designed to be swizzled at all
 
 :::note

website/versioned_docs/version-2.0.0-rc.1/typescript-support.md

@@ -1,8 +1,9 @@
 ---
-id: typescript-support
-title: TypeScript Support
+description: Docusaurus is written in TypeScript and provides first-class TypeScript support.
 ---
 
+# TypeScript Support
+
 Docusaurus is written in TypeScript and provides first-class TypeScript support.
 
 ## Initialization {#initialization}

website/versioned_docs/version-2.0.0-rc.1/using-plugins.md

@@ -79,9 +79,9 @@ module.exports = {
 };
 ```
 
-## Multi-instance plugins and plugin ids {#multi-instance-plugins-and-plugin-ids}
+## Multi-instance plugins and plugin IDs {#multi-instance-plugins-and-plugin-ids}
 
-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`.
+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 = {
@@ -224,7 +224,7 @@ Preset paths can be relative to the config file:
 module.exports = {
   // ...
   // highlight-next-line
-  presets: ['./src/presets/docusaurus-local-preset')],
+  presets: ['./src/presets/docusaurus-local-preset'],
 };
 ```