diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7eee4e1962b7..9992b28ec895 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,80 @@
 # Docusaurus 2 Changelog
 
+## 2.0.0-beta.17 (2022-03-03)
+
+#### :rocket: New Feature
+
+- `docusaurus-plugin-content-blog`, `docusaurus-theme-classic`
+  - [#6783](https://github.com/facebook/docusaurus/pull/6783) feat: allow blog authors email ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### :boom: Breaking Change
+
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#6771](https://github.com/facebook/docusaurus/pull/6771) refactor(theme-classic): replace color mode toggle with button; remove switchConfig ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### :bug: Bug Fix
+
+- `docusaurus-theme-classic`
+  - [#6827](https://github.com/facebook/docusaurus/pull/6827) fix(theme-classic): restore docusaurus search meta ([@slorber](https://github.com/slorber))
+  - [#6767](https://github.com/facebook/docusaurus/pull/6767) fix(theme-classic): allow code tags containing inline elements to stay inline ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-common`
+  - [#6824](https://github.com/facebook/docusaurus/pull/6824) fix(theme-common): breadcrumbs home bug in docs-only ([@slorber](https://github.com/slorber))
+  - [#6816](https://github.com/facebook/docusaurus/pull/6816) fix(theme-common): docs breadcrumbs not working with baseUrl ([@slorber](https://github.com/slorber))
+- `docusaurus-plugin-content-docs`
+  - [#6700](https://github.com/facebook/docusaurus/pull/6700) fix(content-docs): always sort autogenerated sidebar items by file/folder name by default ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus`
+  - [#6812](https://github.com/facebook/docusaurus/pull/6812) fix(core): remove hash/query when filtering existing files for broken link check ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-mdx-loader`
+  - [#6779](https://github.com/facebook/docusaurus/pull/6779) fix(mdx-loader): suppress image reading warning in Yarn PnP; log warning instead of error ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`
+  - [#6762](https://github.com/facebook/docusaurus/pull/6762) fix(create): update broken SVG paths in templates ([@anicholls](https://github.com/anicholls))
+
+#### :nail_care: Polish
+
+- `docusaurus-theme-common`
+  - [#6826](https://github.com/facebook/docusaurus/pull/6826) refactor(theme-common): unify missing context errors ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-classic`, `docusaurus-theme-common`
+  - [#6771](https://github.com/facebook/docusaurus/pull/6771) refactor(theme-classic): replace color mode toggle with button; remove switchConfig ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-theme-classic`
+  - [#6769](https://github.com/facebook/docusaurus/pull/6769) refactor(theme-classic): use Material icon for language dropdown ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-mdx-loader`
+  - [#6792](https://github.com/facebook/docusaurus/pull/6792) fix(mdx-loader): allow image paths to be URL encoded ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### :memo: Documentation
+
+- Other
+  - [#6825](https://github.com/facebook/docusaurus/pull/6825) docs: Adds Netlify one click deploy to README ([@PatelN123](https://github.com/PatelN123))
+  - [#6818](https://github.com/facebook/docusaurus/pull/6818) docs: add deploy with vercel button to README ([@PatelN123](https://github.com/PatelN123))
+  - [#6817](https://github.com/facebook/docusaurus/pull/6817) docs: fix broken links ([@PatelN123](https://github.com/PatelN123))
+  - [#6811](https://github.com/facebook/docusaurus/pull/6811) docs: add homepage banner in support of Ukraine ([@dmitryvinn](https://github.com/dmitryvinn))
+  - [#6813](https://github.com/facebook/docusaurus/pull/6813) docs: mark dyte as opensource in showcase ([@vaibhavshn](https://github.com/vaibhavshn))
+  - [#6776](https://github.com/facebook/docusaurus/pull/6776) docs: make GitHub actions explanation aligned with the code ([@arifszn](https://github.com/arifszn))
+  - [#6772](https://github.com/facebook/docusaurus/pull/6772) docs: add basic documentation about client modules ([@Josh-Cena](https://github.com/Josh-Cena))
+- `create-docusaurus`
+  - [#6815](https://github.com/facebook/docusaurus/pull/6815) fix: consistently use `max-width: 996px` in media queries ([@dstotijn](https://github.com/dstotijn))
+
+#### :house: Internal
+
+- `docusaurus-plugin-content-docs`
+  - [#6821](https://github.com/facebook/docusaurus/pull/6821) test(content-docs): refactor navigation test snapshot ([@Josh-Cena](https://github.com/Josh-Cena))
+- Other
+  - [#6768](https://github.com/facebook/docusaurus/pull/6768) test: add TypeScript template to E2E test matrix ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-utils`
+  - [#6773](https://github.com/facebook/docusaurus/pull/6773) refactor(utils): categorize functions into separate files ([@Josh-Cena](https://github.com/Josh-Cena))
+- `docusaurus-migrate`
+  - [#6761](https://github.com/facebook/docusaurus/pull/6761) chore: various internal fixes ([@Josh-Cena](https://github.com/Josh-Cena))
+
+#### Committers: 8
+
+- Alex Nicholls ([@anicholls](https://github.com/anicholls))
+- Ariful Alam ([@arifszn](https://github.com/arifszn))
+- David Stotijn ([@dstotijn](https://github.com/dstotijn))
+- Dmitry Vinnik ([@dmitryvinn](https://github.com/dmitryvinn))
+- Joshua Chen ([@Josh-Cena](https://github.com/Josh-Cena))
+- Nayan Patel ([@PatelN123](https://github.com/PatelN123))
+- Sébastien Lorber ([@slorber](https://github.com/slorber))
+- Vaibhav Shinde ([@vaibhavshn](https://github.com/vaibhavshn))
+
 ## 2.0.0-beta.16 (2022-02-25)
 
 #### :rocket: New Feature
diff --git a/website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx b/website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx
deleted file mode 100644
index e2aec479dd28..000000000000
--- a/website/versioned_docs/version-2.0.0-beta.15/_partials/swizzleWarning.mdx
+++ /dev/null
@@ -1,5 +0,0 @@
-:::caution
-
-We discourage swizzling of components during the Docusaurus 2 beta phase. The theme components APIs are likely to evolve and have breaking changes. If possible, stick with the default appearance for now.
-
-:::
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md b/website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md
deleted file mode 100644
index 4163bb6e632b..000000000000
--- a/website/versioned_docs/version-2.0.0-beta.15/advanced/swizzling.md
+++ /dev/null
@@ -1,195 +0,0 @@
----
-description: Customize your site's appearance through creating your own theme components
----
-
-# Swizzling
-
-In this section, we will introduce how customization of layout is done in Docusaurus.
-
-> Déja vu...?
-
-This section is similar to [Styling and Layout](../styling-layout.md), but this time, we are going to write more code and go deeper into the internals instead of playing with stylesheets. We will talk about a central concept in Docusaurus customization: **swizzling**, from how to swizzle, to how it works under the hood.
-
-We know you are busy, so we will start with the "how" before going into the "why".
-
-## Swizzling
-
-```mdx-code-block
-import SwizzleWarning from "../_partials/swizzleWarning.mdx"
-
-<SwizzleWarning/>
-```
-
-Docusaurus Themes' components are designed to be replaceable. The replacing is called "swizzle". In Objective C, method swizzling is the process of changing the implementation of an existing selector (method). **In the context of a website, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.** (To gain a deeper understanding of this, you have to understand [how theme components are resolved](#theme-aliases)). To help you get started, we created a command called `docusaurus swizzle`.
-
-### Ejecting theme components
-
-To eject a component provided by the theme, run the following command in your doc site:
-
-```bash npm2yarn
-npm run swizzle [theme name] [component name]
-```
-
-As an example, to swizzle the `<Footer />` component in `@docusaurus/theme-classic` for your site, run:
-
-```bash npm2yarn
-npm run swizzle @docusaurus/theme-classic Footer
-```
-
-This will copy the current `<Footer />` component used by Docusaurus to an `src/theme/Footer` directory under the root of your site, which is where Docusaurus will look for swizzled components. Docusaurus will then use the swizzled component in place of the original one from the theme.
-
-:::note
-
-You need to restart your webpack dev server in order for Docusaurus to know about the new component.
-
-:::
-
-If you run `swizzle` without `component name` or `theme name`, the command will give you a list to choose from. To only list available components, run with the `--list` option:
-
-```bash npm2yarn
-npm run swizzle @docusaurus/theme-classic --list
-```
-
-"Swizzle" is a central concept in Docusaurus, and is a natural product of our [layered theme architecture](#theme-aliases). Note that the command `docusaurus swizzle` is only an automated way to help you swizzle the component: you can still do it manually by creating the `src/theme/Footer.js` file, and Docusaurus will pick that one up when resolving theme components. There's no internal magic behind this command!
-
-### Wrapping theme components {#wrapping-theme-components}
-
-Ejecting a component is risky. It means you have to maintain an almost duplicate copy of the original theme component. Also, it's likely that we will change internal implementations in future versions and break your component, even if you never touched that part of the code.
-
-Very often, you don't need to re-implement a component from scratch, but only to render additional items before or after it, or conditionally call some other logic. In this case, you are still going to swizzle the component—but not making a self-sustained one. Instead, you can delegate most of the logic and layout to the original theme component. The `@theme-original` alias allows you to import the original theme component and wrap it as a higher-order component.
-
-Here is an example to display some text just above the footer, with minimal code duplication.
-
-```js title="src/theme/Footer.js"
-import OriginalFooter from '@theme-original/Footer';
-import React from 'react';
-
-export default function Footer(props) {
-  return (
-    <>
-      <div>Before footer</div>
-      <OriginalFooter {...props} />
-    </>
-  );
-}
-```
-
-Should you be wondering why we have to use `'@theme-original/Footer'` instead of `'@theme/Footer'`, a short explanation is that once you have the swizzled component, the `'@theme/Footer'` alias will now point to your swizzled component, and thus cause a self-import. For a more in-depth explanation, see [theme aliases](#theme-aliases).
-
-## Which component should I swizzle?
-
-Currently, `theme-classic` has about 100 components[^source]! If you want to customize a part of your site's layout, which component should you choose?
-
-[^source]: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme
-
-You can follow the following steps to locate the component to swizzle:
-
-1. **Search.** Our components are semantically named, so you should be able to infer its function from the name. The swizzle CLI allows you to enter part of a component name to narrow down the available choices. For example, if you run `yarn swizzle @docusaurus/theme-classic`, and enter `Doc`, only the docs-related components will be listed.
-2. **Start with a higher-level component.** Components form a tree with some components importing others. Every route will be associated with one top-level component that the route will render (most of them listed in [Routing in content plugins](routing.md#routing-in-content-plugins)). For example, all blog post pages have `@theme/BlogPostPage` as the topmost component. You can start with swizzling this component, and then go down the component tree to locate the component that renders just what you are targeting. Don't forget to unswizzle the rest by deleting the files after you've found the correct one, so you don't maintain too many components.
-3. **Read the source code and use search wisely.** Topmost components are registered by the plugin with `addRoute`, so you can search for `addRoute` and see which component the plugin references. Afterwards, read the code of all components that this component references.
-4. **Ask.** If you still have no idea which component to swizzle to achieve the desired effect, you can reach out for help in one of our [support channels](/community/support).
-
-### Wrapping your site with `<Root>` {#wrapper-your-site-with-root}
-
-The `<Root>` component is one that you probably won't spot. Every component provided by `theme-classic` is ultimately only rendered on certain routes, and will be unmounted during route transition; however, the `<Root>` theme component is rendered at the very top of the Docusaurus SPA, above the router and the theme `<Layout>`, and will **never unmount**, allowing you to wrap your site with additional logic like global state. You can swizzle it by creating a file at `src/theme/Root.js`:
-
-```js title="website/src/theme/Root.js"
-import React from 'react';
-
-// Default implementation, that you can customize
-function Root({children}) {
-  return <>{children}</>;
-}
-
-export default Root;
-```
-
-:::tip
-
-Use this component to render React Context providers and global stateful logic.
-
-:::
-
-## Do I need to swizzle?
-
-Swizzling ultimately means you have to maintain part of the code directly used to build your site, and you have to interact with Docusaurus internal APIs. If you can, think about the following alternatives when customizing your site:
-
-1. **Use CSS.** CSS rules and selectors can often help you achieve a decent degree of customization. Refer to [styling and layout](../styling-layout.md) for more details.
-2. **Use translations.** It may sound surprising, but translations are ultimately just a way to customize the text labels. For example, if your site's default language is `en`, you can still run `yarn write-translations -l en` and edit the `code.json` emitted. Refer to [i18n tutorial](../i18n/i18n-tutorial.md) for more details.
-3. **The smaller, the better.** If swizzling is inevitable, prefer to swizzle only the relevant part and maintain as little code on your own as possible. Swizzling a small component often means less risk of breaking during upgrade. [Wrapping](#wrapping-theme-components) is also a far safer alternative to [ejecting](#ejecting-theme-components).
-
-## Theme aliases
-
-A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias:
-
-```js
-import Navbar from '@theme/Navbar';
-```
-
-The alias `@theme` can refer to a few directories, in the following priority:
-
-1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
-2. A Docusaurus theme package's `theme` directory.
-3. Fallback components provided by Docusaurus core (usually not needed).
-
-This is called a _layered architecture_: a higher-priority layer providing the component would shadow a lower-priority layer, making swizzling possible. Given the following structure:
-
-```
-website
-├── node_modules
-│   └── @docusaurus/theme-classic
-│       └── theme
-│           └── Navbar.js
-└── src
-    └── theme
-        └── Navbar.js
-```
-
-`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. If you are familiar with Objective C where a function's implementation can be swapped during runtime, it's the exact same concept here with changing the target `@theme/Navbar` is pointing to!
-
-We already talked about how the "userland theme" in `src/theme` can re-use a theme component through the [`@theme-original`](#wrapping-theme-components) alias. One theme package can also wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
-
-Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature.
-
-```js
-import InitialCodeBlock from '@theme-init/CodeBlock';
-import React from 'react';
-
-export default function CodeBlock(props) {
-  return props.live ? (
-    <ReactLivePlayground {...props} />
-  ) : (
-    <InitialCodeBlock {...props} />
-  );
-}
-```
-
-Check the code of `@docusaurus/theme-live-codeblock` for details.
-
-:::caution
-
-Unless you want to publish a re-usable "theme enhancer" (like `@docusaurus/theme-live-codeblock`), you likely don't need `@theme-init`.
-
-:::
-
-It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup with three themes/plugins and the site itself all trying to define the same component. Internally, Docusaurus loads these themes as a "stack".
-
-```text
-+-------------------------------------------------+
-|        `website/src/theme/CodeBlock.js`         | <-- `@theme/CodeBlock` always points to the top
-+-------------------------------------------------+
-| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component
-+-------------------------------------------------+
-|  `plugin-awesome-codeblock/theme/CodeBlock.js`  |
-+-------------------------------------------------+
-|     `theme-classic/theme/CodeBlock/index.js`    | <-- `@theme-init/CodeBlock` always points to the bottom
-+-------------------------------------------------+
-```
-
-The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last.
-
-`@theme/*` always points to the topmost component—when `CodeBlock` is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
-
-`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import.
-
-`@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/architecture.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/advanced/architecture.md
rename to website/versioned_docs/version-2.0.0-beta.17/advanced/architecture.md
diff --git a/website/versioned_docs/version-2.0.0-beta.17/advanced/client.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/client.md
new file mode 100644
index 000000000000..be140eac465d
--- /dev/null
+++ b/website/versioned_docs/version-2.0.0-beta.17/advanced/client.md
@@ -0,0 +1,117 @@
+# Client architecture
+
+## Theme aliases {#theme-aliases}
+
+A theme works by exporting a set of components, e.g. `Navbar`, `Layout`, `Footer`, to render the data passed down from plugins. Docusaurus and users use these components by importing them using the `@theme` webpack alias:
+
+```js
+import Navbar from '@theme/Navbar';
+```
+
+The alias `@theme` can refer to a few directories, in the following priority:
+
+1. A user's `website/src/theme` directory, which is a special directory that has the higher precedence.
+2. A Docusaurus theme package's `theme` directory.
+3. Fallback components provided by Docusaurus core (usually not needed).
+
+This is called a _layered architecture_: a higher-priority layer providing the component would shadow a lower-priority layer, making swizzling possible. Given the following structure:
+
+```
+website
+├── node_modules
+│   └── @docusaurus/theme-classic
+│       └── theme
+│           └── Navbar.js
+└── src
+    └── theme
+        └── Navbar.js
+```
+
+`website/src/theme/Navbar.js` takes precedence whenever `@theme/Navbar` is imported. This behavior is called component swizzling. If you are familiar with Objective C where a function's implementation can be swapped during runtime, it's the exact same concept here with changing the target `@theme/Navbar` is pointing to!
+
+We already talked about how the "userland theme" in `src/theme` can re-use a theme component through the [`@theme-original`](#wrapping) alias. One theme package can also wrap a component from another theme, by importing the component from the initial theme, using the `@theme-init` import.
+
+Here's an example of using this feature to enhance the default theme `CodeBlock` component with a `react-live` playground feature.
+
+```js
+import InitialCodeBlock from '@theme-init/CodeBlock';
+import React from 'react';
+
+export default function CodeBlock(props) {
+  return props.live ? (
+    <ReactLivePlayground {...props} />
+  ) : (
+    <InitialCodeBlock {...props} />
+  );
+}
+```
+
+Check the code of `@docusaurus/theme-live-codeblock` for details.
+
+:::caution
+
+Unless you want to publish a re-usable "theme enhancer" (like `@docusaurus/theme-live-codeblock`), you likely don't need `@theme-init`.
+
+:::
+
+It can be quite hard to wrap your mind around these aliases. Let's imagine the following case with a super convoluted setup with three themes/plugins and the site itself all trying to define the same component. Internally, Docusaurus loads these themes as a "stack".
+
+```text
++-------------------------------------------------+
+|        `website/src/theme/CodeBlock.js`         | <-- `@theme/CodeBlock` always points to the top
++-------------------------------------------------+
+| `theme-live-codeblock/theme/CodeBlock/index.js` | <-- `@theme-original/CodeBlock` points to the topmost non-swizzled component
++-------------------------------------------------+
+|  `plugin-awesome-codeblock/theme/CodeBlock.js`  |
++-------------------------------------------------+
+|     `theme-classic/theme/CodeBlock/index.js`    | <-- `@theme-init/CodeBlock` always points to the bottom
++-------------------------------------------------+
+```
+
+The components in this "stack" are pushed in the order of `preset plugins > preset themes > plugins > themes > site`, so the swizzled component in `website/src/theme` always comes out on top because it's loaded last.
+
+`@theme/*` always points to the topmost component—when `CodeBlock` is swizzled, all other components requesting `@theme/CodeBlock` receive the swizzled version.
+
+`@theme-original/*` always points to the topmost non-swizzled component. That's why you can import `@theme-original/CodeBlock` in the swizzled component—it points to the next one in the "component stack", a theme-provided one. Plugin authors should not try to use this because your component could be the topmost component and cause a self-import.
+
+`@theme-init/*` always points to the bottommost component—usually, this comes from the theme or plugin that first provides this component. Individual plugins / themes trying to enhance code block can safely use `@theme-init/CodeBlock` to get its basic version. Site creators should generally not use this because you likely want to enhance the _topmost_ instead of the _bottommost_ component. It's also possible that the `@theme-init/CodeBlock` alias does not exist at all—Docusaurus only creates it when it points to a different one from `@theme-original/CodeBlock`, i.e. when it's provided by more than one theme. We don't waste aliases!
+
+## Client modules {#client-modules}
+
+Client modules are part of your site's bundle, just like theme components. However, they are usually side-effect-ful. Client modules are anything that can be `import`ed by Webpack—CSS, JS, etc. JS scripts usually work on the global context, like registering event listeners, creating global variables...
+
+These modules are imported globally before React even renders the initial UI.
+
+```js title="App.tsx"
+// How it works under the hood
+import '@generated/client-modules';
+```
+
+Plugins and sites can both declare client modules, through [`getClientModules`](../api/plugin-methods/lifecycle-apis.md#getClientModules) and [`siteConfig.clientModules`](../api/docusaurus.config.js.md#clientModules), respectively.
+
+Client modules are called during server-side rendering as well, so remember to check the [execution environment](./ssg.md#escape-hatches) before accessing client-side globals.
+
+```js title="mySiteGlobalJs.js"
+import ExecutionEnvironment from '@docusaurus/ExecutionEnvironment';
+
+if (ExecutionEnvironment.canUseDOM) {
+  // As soon as the site loads in the browser, register a global event listener
+  window.addEventListener('keydown', (e) => {
+    if (e.code === 'Period') {
+      location.assign(location.href.replace('.com', '.dev'));
+    }
+  });
+}
+```
+
+CSS stylesheets imported as client modules are [global](../styling-layout.md#global-styles).
+
+```css title="mySiteGlobalCss.css"
+/* This stylesheet is global. */
+.globalSelector {
+  color: red;
+}
+```
+
+<!-- TODO client module lifecycles -->
+<!-- https://github.com/facebook/docusaurus/issues/3399 -->
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/index.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/index.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/advanced/index.md
rename to website/versioned_docs/version-2.0.0-beta.17/advanced/index.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md
rename to website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md
index c309f4b53637..3e6e9f969f46 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/advanced/plugins.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/advanced/plugins.md
@@ -80,11 +80,11 @@ Plugins come as several types:
 
 You can access them on the client side with `useDocusaurusContext().siteMetadata.pluginVersions`.
 
-## Plugin design
+## Plugin design {#plugin-design}
 
 Docusaurus' implementation of the plugins system provides us with a convenient way to hook into the website's lifecycle to modify what goes on during development/build, which involves (but is not limited to) extending the webpack config, modifying the data loaded, and creating new components to be used in a page.
 
-### Theme design
+### Theme design {#theme-design}
 
 When plugins have loaded their content, the data is made available to the client side through actions like [`createData` + `addRoute`](../api/plugin-methods/lifecycle-apis.md#addRoute) or [`setGlobalData`](../api/plugin-methods/lifecycle-apis.md#setGlobalData). This data has to be _serialized_ to plain strings, because [plugins and themes run in different environments](./architecture.md). Once the data arrives on the client side, the rest becomes familiar to React developers: data is passed along components, components are bundled with Webpack, and rendered to the window through `ReactDOM.render`...
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/routing.md
similarity index 96%
rename from website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md
rename to website/versioned_docs/version-2.0.0-beta.17/advanced/routing.md
index 09bc837490fd..9aca36f249bb 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/advanced/routing.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/advanced/routing.md
@@ -13,7 +13,7 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
 
 Docusaurus' routing system follows single-page application conventions: one route, one component. In this section, we will begin by talking about routing within the three content plugins (docs, blog, and pages), and then go beyond to talk about the underlying routing system.
 
-## Routing in content plugins
+## Routing in content plugins {#routing-in-content-plugins}
 
 Every content plugin provides a `routeBasePath` option. It defines where the plugins append their routes to. By default, the docs plugin puts its routes under `/docs`; the blog plugin, `/blog`; and the pages plugin, `/`. You can think about the route structure like this:
 
@@ -25,13 +25,13 @@ Changing `routeBasePath` can effectively alter your site's route structure. For
 
 Next, let's look at how the three plugins structure their own "boxes of subroutes".
 
-### Pages routing
+### Pages routing {#pages-routing}
 
 Pages routing are straightforward: the file paths directly map to URLs, without any other way to customize. See the [pages docs](../guides/creating-pages.md#routing) for more information.
 
 The component used for Markdown pages is `@theme/MDXPage`. React pages are directly used as the route's component.
 
-### Blog routing
+### Blog routing {#blog-routing}
 
 The blog creates the following routes:
 
@@ -52,7 +52,7 @@ The blog creates the following routes:
   - The route is customizable through the `archiveBasePath` option.
   - The component is `@theme/BlogArchivePage`.
 
-### Docs routing
+### Docs routing {#docs-routing}
 
 The docs is the only plugin that creates **nested routes**. At the top, it registers [**version paths**](../guides/docs/versioning.md): `/`, `/next`, `/2.0.0-beta.13`... which provide the version context, including the layout and sidebar. This ensures that when switching between individual docs, the sidebar's state is preserved, and that you can switch between versions through the navbar dropdown while staying on the same doc. The component used is `@theme/DocPage`.
 
@@ -69,12 +69,14 @@ The individual docs are rendered in the remaining space after the navbar, footer
 
 The doc's `slug` front matter customizes the last part of the route, but the base route is always defined by the plugin's `routeBasePath` and the version's `path`.
 
-### File paths and URL paths
+### File paths and URL paths {#file-paths-and-url-paths}
 
 Throughout the documentation, we always try to be unambiguous about whether we are talking about file paths or URL paths. Content plugins usually map file paths directly to URL paths, for example, `./docs/advanced/routing.md` will become `/docs/advanced/routing`. However, with `slug`, you can make URLs totally decoupled from the file structure.
 
 When writing links in Markdown, you could either mean a _file path_, or a _URL path_, which Docusaurus would use several heuristics to determine.
 
+- If the path has a `@site` prefix, it is _always_ an asset file path.
+- If the path has an `http(s)://` prefix, it is _always_ a URL path.
 - If the path doesn't have an extension, it is a URL path. For example, a link `[page](../plugins)` on a page with URL `/docs/advanced/routing` will link to `/docs/plugins`. Docusaurus will only detect broken links when building your site (when it knows the full route structure), but will make no assumptions about the existence of a file. It is exactly equivalent to writing `<a href="../plugins">page</a>` in a JSX file.
 - 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.
@@ -126,7 +128,7 @@ The following directory structure may help you visualize this file -> URL mappin
 
 So much about content plugins. Let's take one step back and talk about how routing works in a Docusaurus app in general.
 
-## Routes become HTML files
+## Routes become HTML files {#routes-become-html-files}
 
 Because Docusaurus is a server-side rendering framework, all routes generated will be server-side rendered into static HTML files. If you are familiar with the behavior of HTTP servers like [Apache2](https://httpd.apache.org/docs/trunk/getting-started.html), you will understand how this is done: when the browser sends a request to the route `/docs/advanced/routing`, the server interprets that as request for the HTML file `/docs/advanced/routing/index.html`, and returns that.
 
@@ -200,7 +202,7 @@ For example, the emitted HTML would contain links like `<link rel="preload" href
 
 Localized sites have the locale as part of the base URL as well. For example, `https://docusaurus.io/zh-CN/docs/advanced/routing/` has base URL `/zh-CN/`.
 
-## Generating and accessing routes
+## Generating and accessing routes {#generating-and-accessing-routes}
 
 The `addRoute` lifecycle action is used to generate routes. It registers a piece of route config to the route tree, giving a route, a component, and props that the component needs. The props and the component are both provided as paths for the bundler to `require`, because as explained in the [architecture overview](architecture.md), server and client only communicate through temp files.
 
@@ -242,7 +244,7 @@ export function PageRoute() {
 </BrowserWindow>
 ```
 
-## Escaping from SPA redirects
+## Escaping from SPA redirects {#escaping-from-spa-redirects}
 
 Docusaurus builds a [single-page application](https://developer.mozilla.org/en-US/docs/Glossary/SPA), where route transitions are done through the `history.push()` method of React router. This operation is done on the client side. However, the prerequisite for a route transition to happen this way is that the target URL is known to our router. Otherwise, the router catches this path and displays a 404 page instead.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md b/website/versioned_docs/version-2.0.0-beta.17/advanced/ssg.md
similarity index 97%
rename from website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md
rename to website/versioned_docs/version-2.0.0-beta.17/advanced/ssg.md
index 6c478e67e5cf..b5b4e81f9f58 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/advanced/ssg.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/advanced/ssg.md
@@ -92,7 +92,7 @@ export default function expensiveComp() {
 </Tabs>
 </details>
 
-## Understanding SSR
+## Understanding SSR {#understanding-ssr}
 
 React is not just a dynamic UI runtime—it's also a templating engine. Because Docusaurus sites mostly contain static contents, it should be able to work without any JavaScript (which React runs in), but only plain HTML/CSS. And that's what server-side rendering offers: statically rendering your React code into HTML, without any dynamic content. An HTML file has no concept of client state (it's purely markup), hence it shouldn't rely on browser APIs.
 
@@ -100,7 +100,7 @@ These HTML files are the first to arrive at the user's browser screen when a URL
 
 In CSR-only apps, all DOM elements are generated on client side with React, and the HTML file only ever contains one root element for React to mount DOM to; in SSR, React is already facing a fully built HTML page, and it only needs to correlate the DOM elements with the virtual DOM in its model. This step is called "hydration". After React has hydrated the static markup, the app starts to work as any normal React app.
 
-## Escape hatches
+## Escape hatches {#escape-hatches}
 
 If you want to render any dynamic content on your screen that relies on the browser API to be functional at all, for example:
 
@@ -122,7 +122,7 @@ You can read more about this pitfall in [The Perils of Rehydration](https://www.
 
 We provide several more reliable ways to escape SSR.
 
-### `<BrowserOnly>`
+### `<BrowserOnly>` {#browseronly}
 
 If you need to render some component in browser only (for example, because the component relies on browser specifics to be functional at all), one common approach is to wrap your component with [`<BrowserOnly>`](../docusaurus-core.md#browseronly) to make sure it's invisible during SSR and only rendered in CSR.
 
@@ -163,7 +163,7 @@ function MyComponent() {
 
 While you may expect that `BrowserOnly` hides away the children during server-side rendering, it actually can't. When the React renderer tries to render this JSX tree, it does see the `{window.location.href}` variable as a node of this tree and tries to render it, although it's actually not used! Using a function ensures that we only let the renderer see the browser-only component when it's needed.
 
-### `useIsBrowser`
+### `useIsBrowser` {#useisbrowser}
 
 You can also use the `useIsBrowser()` hook to test if the component is currently in a browser environment. It returns `false` in SSR and `true` is CSR, after first client render. Use this hook if you only need to perform certain conditional operations on client-side, but not render an entirely different UI.
 
@@ -177,7 +177,7 @@ function MyComponent() {
 }
 ```
 
-### `useEffect`
+### `useEffect` {#useeffect}
 
 Lastly, you can put your logic in `useEffect()` to delay its execution until after first CSR. This is most appropriate if you are only performing side-effects but don't _get_ data from the client state.
 
@@ -191,7 +191,7 @@ function MyComponent() {
 }
 ```
 
-### `ExecutionEnvironment`
+### `ExecutionEnvironment` {#executionenvironment}
 
 The [`ExecutionEnvironment`](../docusaurus-core.md#executionenvironment) namespace contains several values, and `canUseDOM` is an effective way to detect browser environment.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/docusaurus.config.js.md b/website/versioned_docs/version-2.0.0-beta.17/api/docusaurus.config.js.md
similarity index 96%
rename from website/versioned_docs/version-2.0.0-beta.15/api/docusaurus.config.js.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/docusaurus.config.js.md
index ab50dc53956c..5a52885277b7 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/docusaurus.config.js.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/docusaurus.config.js.md
@@ -284,18 +284,6 @@ module.exports = {
       defaultMode: 'light',
       disableSwitch: false,
       respectPrefersColorScheme: true,
-      switchConfig: {
-        darkIcon: '🌙',
-        lightIcon: '\u2600',
-        // React inline style object
-        // see https://reactjs.org/docs/dom-elements.html#style
-        darkIconStyle: {
-          marginLeft: '2px',
-        },
-        lightIconStyle: {
-          marginLeft: '1px',
-        },
-      },
     },
     navbar: {
       title: 'Site Title',
@@ -450,7 +438,7 @@ module.exports = {
 
 ### `clientModules` {#clientmodules}
 
-An array of client modules to load globally on your site:
+An array of [client modules](../advanced/client.md#client-modules) to load globally on your site:
 
 Example:
 
@@ -463,8 +451,6 @@ module.exports = {
 };
 ```
 
-See also: [`getClientModules()`](./plugin-methods/lifecycle-apis.md#getClientModules).
-
 ### `ssrTemplate` {#ssrtemplate}
 
 An HTML template written in [Eta's syntax](https://eta.js.org/docs/syntax#syntax-overview) that will be used to render your application. This can be used to set custom attributes on the `body` tags, additional `meta` tags, customize the `viewport`, etc. Please note that Docusaurus will rely on the template to be correctly structured in order to function properly, once you do customize it, you will have to make sure that your template is compliant with the requirements from `upstream`.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/README.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/README.md
index b764d726d51d..0e9d816c6f6d 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/README.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/README.md
@@ -8,14 +8,14 @@ This section is a work in progress. Anchor links or even URLs are not guaranteed
 
 Plugin APIs are shared by themes and plugins—themes are loaded just like plugins.
 
-## Plugin module
+## Plugin module {#plugin-module}
 
 Every plugin is imported as a module. The module is expected to have the following members:
 
 - A **default export**: the constructor function for the plugin.
 - **Named exports**: the [static methods](./static-methods.md) called before plugins are initialized.
 
-## Plugin constructor
+## Plugin constructor {#plugin-constructor}
 
 The plugin module's default export is a constructor function with the signature `(context: LoadContext, options: PluginOptions) => Plugin | Promise<Plugin>`.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/_category_.yml b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/_category_.yml
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/_category_.yml
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/_category_.yml
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/extend-infrastructure.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/extend-infrastructure.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/extend-infrastructure.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/extend-infrastructure.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/i18n-lifecycles.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/i18n-lifecycles.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/i18n-lifecycles.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/i18n-lifecycles.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/lifecycle-apis.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/lifecycle-apis.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/lifecycle-apis.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/lifecycle-apis.md
index b25455eed31f..e8638d6bb956 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/lifecycle-apis.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/lifecycle-apis.md
@@ -378,7 +378,7 @@ module.exports = function (context, options) {
 
 ## `getClientModules()` {#getClientModules}
 
-Returns an array of paths to the modules that are to be imported into the client bundle. These modules are imported globally before React even renders the initial UI.
+Returns an array of paths to the [client modules](../../advanced/client.md#client-modules) that are to be imported into the client bundle.
 
 As an example, to make your theme load a `customCss` or `customJs` file path from `options` passed in by the user:
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/static-methods.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/static-methods.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugin-methods/static-methods.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugin-methods/static-methods.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/_category_.yml b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/_category_.yml
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/_category_.yml
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/_category_.yml
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/overview.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/overview.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/overview.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/overview.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-client-redirects.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-client-redirects.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-client-redirects.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-client-redirects.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-blog.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-blog.md
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-blog.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-blog.md
index b456cc31251b..7eda77338a4c 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-blog.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-blog.md
@@ -54,6 +54,7 @@ Accepted fields:
 | `blogPostComponent` | `string` | `'@theme/BlogPostPage'` | Root component of each blog post page. |
 | `blogTagsListComponent` | `string` | `'@theme/BlogTagsListPage'` | Root component of the tags list page |
 | `blogTagsPostsComponent` | `string` | `'@theme/BlogTagsPostsPage'` | Root component of the "posts containing tag" page. |
+| `blogArchiveComponent` | `string` | `'@theme/BlogArchivePage'` | Root component of the blog archive page. |
 | `remarkPlugins` | `any[]` | `[]` | Remark plugins passed to MDX. |
 | `rehypePlugins` | `any[]` | `[]` | Rehype plugins passed to MDX. |
 | `beforeDefaultRemarkPlugins` | `any[]` | `[]` | Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins. |
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-docs.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-docs.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-docs.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-docs.md
index 1c706ef12876..2c97cd4ab78e 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-docs.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-docs.md
@@ -32,6 +32,7 @@ Accepted fields:
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | `path` | `string` | `'docs'` | Path to data on filesystem relative to site dir. |
+| `breadcrumbs` | `boolean` | `true` | To enable or disable the breadcrumbs on docs pages. |
 | `editUrl` | <code>string \| EditUrlFunction</code> | `undefined` | Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links. |
 | `editLocalizedFiles` | `boolean` | `false` | The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function. |
 | `editCurrentVersion` | `boolean` | `false` | The edit URL will always target the current version doc instead of older versions. Ignored when `editUrl` is a function. |
@@ -94,6 +95,7 @@ type SidebarGenerator = (generatorArgs: {
     sidebarPosition?: number | undefined;
   }>; // all the docs of that version (unfiltered)
   numberPrefixParser: PrefixParser; // numberPrefixParser configured for this plugin
+  categoriesMetadata: Record<string, CategoryMetadata>; // key is the path relative to the doc directory, value is the category metadata file's content
   isCategoryIndex: CategoryIndexMatcher; // the default category index matcher, that you can override
   defaultSidebarItemsGenerator: SidebarGenerator; // useful to re-use/enhance default sidebar generation logic from Docusaurus
 }) => Promise<SidebarItem[]>;
@@ -126,6 +128,7 @@ Most Docusaurus users configure this plugin through the preset options.
 
 const config = {
   path: 'docs',
+  breadcrumbs: true,
   // Simple use-case: string editUrl
   // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
   // Advanced use-case: functional editUrl
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-pages.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-pages.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-content-pages.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-content-pages.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-debug.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-debug.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-debug.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-debug.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-google-analytics.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-google-analytics.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-google-analytics.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-google-analytics.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-google-gtag.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-google-gtag.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-google-gtag.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-google-gtag.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-ideal-image.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-ideal-image.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-ideal-image.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-ideal-image.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-pwa.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-pwa.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-pwa.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-pwa.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-sitemap.md b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-sitemap.md
similarity index 97%
rename from website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-sitemap.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-sitemap.md
index 06138111c360..6c8bd87d32c1 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/plugins/plugin-sitemap.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/plugins/plugin-sitemap.md
@@ -70,3 +70,5 @@ const config = {
   priority: 0.5,
 };
 ```
+
+You can find your sitemap at `/sitemap.xml`.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/_category_.yml b/website/versioned_docs/version-2.0.0-beta.17/api/themes/_category_.yml
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/_category_.yml
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/_category_.yml
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/overview.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/overview.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/overview.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/overview.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-classic.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-classic.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-classic.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-classic.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-configuration.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-configuration.md
similarity index 97%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-configuration.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-configuration.md
index e79cf89614cf..108aa6aa78d3 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-configuration.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-configuration.md
@@ -28,11 +28,6 @@ Accepted fields:
 | `defaultMode` | <code>'light' \| 'dark'</code> | `'light'` | The color mode when user first visits the site. |
 | `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`. |
-| `switchConfig` | _See below_ | _See below_ | Dark/light switch icon options. |
-| `switchConfig.darkIcon` | `string` | `'🌜'` | Icon for the switch while in dark mode. |
-| `switchConfig.darkIconStyle` | JSX style object (see [documentation](https://reactjs.org/docs/dom-elements.html#style)) | `{}` | CSS to apply to dark icon. |
-| `switchConfig.lightIcon` | `string` | `'🌞'` | Icon for the switch while in light mode. |
-| `switchConfig.lightIconStyle` | JSX style object | `{}` | CSS to apply to light icon. |
 
 </APITable>
 
@@ -46,18 +41,6 @@ module.exports = {
       defaultMode: 'light',
       disableSwitch: false,
       respectPrefersColorScheme: false,
-      switchConfig: {
-        darkIcon: '🌙',
-        darkIconStyle: {
-          marginLeft: '2px',
-        },
-        // Unicode icons such as '\u2600' will work
-        // Unicode with 5 chars require brackets: '\u{1F602}'
-        lightIcon: '\u{1F602}',
-        lightIconStyle: {
-          marginLeft: '1px',
-        },
-      },
     },
     // highlight-end
   },
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-live-codeblock.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-live-codeblock.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-live-codeblock.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-live-codeblock.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-search-algolia.md b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-search-algolia.md
similarity index 79%
rename from website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-search-algolia.md
rename to website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-search-algolia.md
index 077a4ab13bf1..05e2f767fe12 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/api/themes/theme-search-algolia.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/api/themes/theme-search-algolia.md
@@ -11,7 +11,7 @@ This theme provides a `@theme/SearchBar` component that integrates with Algolia
 npm install --save @docusaurus/theme-search-algolia
 ```
 
-This theme also adds search page available at `/search` (as swizzlable `SearchPage` component) path with OpenSearch support.
+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.
 
 :::tip
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example-banner.png b/website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example-banner.png
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example-banner.png
rename to website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example-banner.png
diff --git a/website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.docx b/website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.docx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.docx
rename to website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.docx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.xyz b/website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.xyz
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/assets/docusaurus-asset-example.xyz
rename to website/versioned_docs/version-2.0.0-beta.17/assets/docusaurus-asset-example.xyz
diff --git a/website/versioned_docs/version-2.0.0-beta.15/blog.mdx b/website/versioned_docs/version-2.0.0-beta.17/blog.mdx
similarity index 92%
rename from website/versioned_docs/version-2.0.0-beta.15/blog.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/blog.mdx
index 06777ff89e79..3e0173879a5f 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/blog.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/blog.mdx
@@ -69,39 +69,7 @@ This is my first post on Docusaurus 2.
 A whole bunch of exploration to follow.
 ```
 
-:::note
-
-Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
-
-This naming convention is optional, and you can provide the date as front matter.
-
-<details>
-<summary>Example supported patterns</summary>
-
-| Pattern | Example |
-| --- | --- |
-| Single file | `2021-05-28-my-blog-post-title.md` |
-| MDX file | `2021-05-28-my-blog-post-title.mdx` |
-| Single folder + `index.md` | `2021-05-28-my-blog-post-title/index.md` |
-| Folder named by date | `2021-05-28/my-blog-post-title.md` |
-| Nested folders by date | `2021/05/28/my-blog-post-title.md` |
-| Partially nested folders by date | `2021/05-28-my-blog-post-title.md` |
-| Nested folders + `index.md` | `2021/05/28/my-blog-post-title/index.md` |
-| Date in the middle of path | `category/2021/05-28-my-blog-post-title.md` |
-
-The date will be excised from the path and appended to the beginning of the URL slug.
-
-</details>
-
-:::
-
-:::tip
-
-Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
-
-:::
-
-The only required field in the front matter is `title`; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
+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).
 
 ## Blog list {#blog-list}
 
@@ -173,9 +141,51 @@ module.exports = {
 };
 ```
 
+## Blog post date {#blog-post-date}
+
+Docusaurus will extract a `YYYY-MM-DD` date from a file/folder name such as `YYYY-MM-DD-my-blog-post-title.md`.
+
+<details>
+<summary>Example supported patterns</summary>
+
+| Pattern | Example |
+| --- | --- |
+| Single file | `2021-05-28-my-blog-post-title.md` |
+| MDX file | `2021-05-28-my-blog-post-title.mdx` |
+| Single folder + `index.md` | `2021-05-28-my-blog-post-title/index.md` |
+| Folder named by date | `2021-05-28/my-blog-post-title.md` |
+| Nested folders by date | `2021/05/28/my-blog-post-title.md` |
+| Partially nested folders by date | `2021/05-28-my-blog-post-title.md` |
+| Nested folders + `index.md` | `2021/05/28/my-blog-post-title/index.md` |
+| Date in the middle of path | `category/2021/05-28-my-blog-post-title.md` |
+
+The date will be excised from the path and appended to the beginning of the URL slug.
+
+</details>
+
+:::tip
+
+Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
+
+:::
+
+This naming convention is optional, and you can also provide the date as front matter. Since the front matter follows YAML syntax where the datetime notation is supported, you can use front matter if you need more fine-grained publish dates. For example, if you have multiple posts published on the same day, you can order them according to the time of the day:
+
+```md title="earlier-post.md"
+---
+date: 2021-09-13T10:00
+---
+```
+
+```md title="later-post.md"
+---
+date: 2021-09-13T18:00
+---
+```
+
 ## Blog post authors {#blog-post-authors}
 
-Use the `authors` front matter field to declare blog post authors.
+Use the `authors` front matter field to declare blog post authors. An author should have at least a `name` or an `image_url`. Docusaurus uses information like `url`, `email`, and `title`, but any other information is allowed.
 
 ### Inline authors {#inline-authors}
 
@@ -192,6 +202,7 @@ authors:
   title: Co-creator of Docusaurus 1
   url: https://github.com/JoelMarcey
   image_url: https://github.com/JoelMarcey.png
+  email: jimarcey@gmail.com
 ---
 ```
 
@@ -205,6 +216,7 @@ authors:
     title: Co-creator of Docusaurus 1
     url: https://github.com/JoelMarcey
     image_url: https://github.com/JoelMarcey.png
+    email: jimarcey@gmail.com
   - name: Sébastien Lorber
     title: Docusaurus maintainer
     url: https://sebastienlorber.com
@@ -249,6 +261,7 @@ jmarcey:
   title: Co-creator of Docusaurus 1
   url: https://github.com/JoelMarcey
   image_url: https://github.com/JoelMarcey.png
+  email: jimarcey@gmail.com
 
 slorber:
   name: Sébastien Lorber
@@ -343,6 +356,12 @@ website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
 
 An author, either declared through front matter or through the authors map, needs to have a name or an avatar, or both. If all authors of a post don't have names, Docusaurus will display their avatars compactly. See [this test post](/tests/blog/2022/01/20/image-only-authors) for the effect.
 
+:::caution Feed generation
+
+[RSS feeds](#feed) require the author's email to be set for the author to appear in the feed.
+
+:::
+
 ## Reading time {#reading-time}
 
 Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/browser-support.md b/website/versioned_docs/version-2.0.0-beta.17/browser-support.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/browser-support.md
rename to website/versioned_docs/version-2.0.0-beta.17/browser-support.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/cli.md b/website/versioned_docs/version-2.0.0-beta.17/cli.md
similarity index 81%
rename from website/versioned_docs/version-2.0.0-beta.15/cli.md
rename to website/versioned_docs/version-2.0.0-beta.17/cli.md
index b2593ca4b058..f300d26abef7 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/cli.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/cli.md
@@ -85,55 +85,37 @@ For advanced minification of CSS bundle, we use the [advanced cssnano preset](ht
 
 :::
 
-### `docusaurus swizzle [siteDir]` {#docusaurus-swizzle-sitedir}
+### `docusaurus swizzle [themeName] [componentName] [siteDir]` {#docusaurus-swizzle}
 
-```mdx-code-block
-import SwizzleWarning from "./_partials/swizzleWarning.mdx"
-
-<SwizzleWarning/>
-```
-
-Change any Docusaurus theme components to your liking with `npm run swizzle`.
+[Swizzle](./swizzling.md) a theme component to customize it.
 
 ```bash npm2yarn
 npm run swizzle [themeName] [componentName] [siteDir]
 
 # Example (leaving out the siteDir to indicate this directory)
-npm run swizzle @docusaurus/theme-classic DocSidebar
+npm run swizzle @docusaurus/theme-classic Footer -- --eject
 ```
 
-Running the command will copy the relevant theme files to your site folder. You may then make any changes to it and Docusaurus will use it instead of the one provided from the theme.
-
-`npm run swizzle` without `themeName` lists all the themes available for swizzling; similarly, `npm run swizzle [themeName]` without `componentName` lists all the components available for swizzling.
-
-#### Options {#options-2}
+The swizzle CLI is interactive and will guide you through the whole [swizzle process](./swizzling.md).
 
-| Name               | Description                            |
-| ------------------ | -------------------------------------- |
-| `themeName`        | The name of the theme you are using.   |
-| `swizzleComponent` | The name of the component to swizzle.  |
-| `--danger`         | Allow swizzling of unstable components |
-| `--typescript`     | Swizzle TypeScript components          |
+#### Options {#options-swizzle}
 
-An example to use `--danger` flag let's consider the below code:
-
-```bash npm2yarn
-npm run swizzle @docusaurus/theme-classic Logo -- --danger
-```
+| Name            | Description                                          |
+| --------------- | ---------------------------------------------------- |
+| `themeName`     | The name of the theme to swizzle from.               |
+| `componentName` | The name of the theme component to swizzle.          |
+| `--list`        | Display components available for swizzling           |
+| `--eject`       | [Eject](./swizzling.md#ejecting) the theme component |
+| `--wrap`        | [Wrap](./swizzling.md#wrapping) the theme component  |
+| `--danger`      | Allow immediate swizzling of unsafe components       |
+| `--typescript`  | Swizzle the TypeScript variant component             |
 
 :::caution
 
-Unstable Components: components that have a higher risk of breaking changes due to internal refactorings.
+Unsafe components have a higher risk of breaking changes due to internal refactorings.
 
 :::
 
-To unswizzle a component, simply delete the files of the swizzled component.
-
-<!--
-TODO a separate section for swizzle tutorial.
-To learn more about swizzling, check [here](#).
--->
-
 ### `docusaurus deploy [siteDir]` {#docusaurus-deploy-sitedir}
 
 Deploys your site with [GitHub Pages](https://pages.github.com/). Check out the docs on [deployment](deployment.mdx#deploying-to-github-pages) for more details.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/configuration.md b/website/versioned_docs/version-2.0.0-beta.17/configuration.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/configuration.md
rename to website/versioned_docs/version-2.0.0-beta.17/configuration.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/deployment.mdx b/website/versioned_docs/version-2.0.0-beta.17/deployment.mdx
similarity index 89%
rename from website/versioned_docs/version-2.0.0-beta.15/deployment.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/deployment.mdx
index fbae1fbecbf6..d2016ed0d58f 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/deployment.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/deployment.mdx
@@ -54,7 +54,38 @@ Use [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slash-gui
 
 :::
 
-## Choosing a hosting provider
+## Using environment variables {#using-environment-variables}
+
+Putting potentially sensitive information in the environment is common practice. However, in a typical Docusaurus website, the `docusaurus.config.js` file is the only interface to the Node.js environment (see [our architecture overview](advanced/architecture.md)), while everything else—MDX pages, React components... are client side and do not have direct access to the `process` global. In this case, you can consider using [`customFields`](api/docusaurus.config.js.md#customfields) to pass environment variables to the client side.
+
+```js title="docusaurus.config.js"
+// If you are using dotenv (https://www.npmjs.com/package/dotenv)
+require('dotenv').config();
+
+module.exports = {
+  title: '...',
+  url: process.env.URL, // You can use environment variables to control site specifics as well
+  // highlight-start
+  customFields: {
+    // Put your custom environment here
+    teamEmail: process.env.EMAIL,
+  },
+  // highlight-end
+};
+```
+
+```jsx title="home.jsx"
+import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+
+export default function Home() {
+  const {
+    siteConfig: {customFields},
+  } = useDocusaurusContext();
+  return <div>Contact us through {customFields.teamEmail}!</div>;
+}
+```
+
+## Choosing a hosting provider {#choosing-a-hosting-provider}
 
 There are a few common hosting options:
 
@@ -182,7 +213,7 @@ Refer to [slorber/trailing-slash-guide](https://github.com/slorber/trailing-slas
 
 Deploying your Docusaurus project to [Vercel](https://vercel.com/) will provide you with [various benefits](https://vercel.com/) in the areas of performance and ease of use.
 
-To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/git-integrations), make sure it has been pushed to a Git repository.
+To deploy your Docusaurus project with a [Vercel for Git Integration](https://vercel.com/docs/concepts/git), make sure it has been pushed to a Git repository.
 
 Import the project into Vercel using the [Import Flow](https://vercel.com/import/git). During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found [here](https://vercel.com/docs/build-step#build-&-development-settings).
 
@@ -308,12 +339,12 @@ Alternatively, you can use SSH (`USE_SSH=true`) to log in.
 
 [GitHub Actions](https://help.github.com/en/actions) allow you to automate, customize, and execute your software development workflows right in your repository.
 
-The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), under a folder called `website/`, and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _deployment branch_ is `gh-pages`).
+The workflow examples below assume your website source resides in the `main` branch of your repository (the _source branch_ is `main`), and your [publishing source](https://help.github.com/en/github/working-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site) is configured for the `gh-pages` branch (the _deployment branch_ is `gh-pages`).
 
 Our goal is that:
 
-1. When a new pull request is made to `main` and updates `website/`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
-2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly and `website/` is updated, it will be built and deployed to the `gh-pages` branch. After that, the new build output will be served on the GitHub Pages site. This job will be called `deploy`.
+1. When a new pull request is made to `main`, there's an action that ensures the site builds successfully, without actually deploying. This job will be called `test-deploy`.
+2. When a pull request is merged to the `main` branch or someone pushes to the `main` branch directly, it will be built and deployed to the `gh-pages` branch. After that, the new build output will be served on the GitHub Pages site. This job will be called `deploy`.
 
 Here are two approaches to deploying your docs with GitHub Actions. Based on the location of your deployment branch (`gh-pages`), choose the relevant tab below:
 
@@ -324,7 +355,7 @@ Here are two approaches to deploying your docs with GitHub Actions. Based on the
 <Tabs>
 <TabItem value="same" label="Same">
 
-While you can have both jobs defined in the same workflow file, the `deploy` job will always be listed as skipped in the PR check suite status. That's added noise providing no value to the review process, and as you cannot easily share common snippets, it is better to manage them as separate workflows instead.
+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).
 
@@ -334,10 +365,12 @@ We will use a popular third-party deployment action: [peaceiris/actions-gh-pages
 
 Add these two workflow files:
 
-:::warning
+:::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.
 
+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.
+
 :::
 
 ```yml title=".github/workflows/deploy.yml"
@@ -345,8 +378,10 @@ name: Deploy to GitHub Pages
 
 on:
   push:
-    branches: [main]
-    paths: [website/**]
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
 
 jobs:
   deploy:
@@ -356,13 +391,13 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 14.x
+          node-version: 16.x
           cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
       - name: Build website
-        working-directory: website
-        run: |
-          yarn install --frozen-lockfile
-          yarn build
+        run: yarn build
 
       # Popular action to deploy to GitHub Pages:
       # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
@@ -371,8 +406,9 @@ jobs:
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           # Build output to publish to the `gh-pages` branch:
-          publish_dir: ./website/build
-          # Assign commit authorship to the official GH-Actions bot for deploys to `gh-pages` branch:
+          publish_dir: ./build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
           # https://github.com/actions/checkout/issues/13#issuecomment-724415212
           # The GH actions bot is used by default if you didn't specify the two fields.
           # You can swap them out with your own user credentials.
@@ -385,8 +421,10 @@ name: Test deployment
 
 on:
   pull_request:
-    branches: [main]
-    paths: [website/**]
+    branches:
+      - main
+    # Review gh actions docs if you want to further define triggers, paths, etc
+    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
 
 jobs:
   test-deploy:
@@ -396,13 +434,13 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 14.x
+          node-version: 16.x
           cache: yarn
-      - name: Test build
-        working-directory: website
-        run: |
-          yarn install --frozen-lockfile
-          yarn build
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build
 ```
 
 </details>
@@ -448,12 +486,12 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 14.x
+          node-version: 16.x
           cache: yarn
-      - name: Test deployment
-        run: |
-          yarn install --frozen-lockfile
-          yarn build
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+      - name: Test build website
+        run: yarn build
   deploy:
     if: github.event_name != 'pull_request'
     runs-on: ubuntu-latest
@@ -461,7 +499,7 @@ jobs:
       - uses: actions/checkout@v2
       - uses: actions/setup-node@v3
         with:
-          node-version: 14.x
+          node-version: 16.x
           cache: yarn
       - uses: webfactory/ssh-agent@v0.5.0
         with:
@@ -733,6 +771,10 @@ You can deploy any other changes in the future with the command `surge`.
 
 See [docs](https://docs.quantcdn.io/docs/cli/continuous-integration) and [blog](https://www.quantcdn.io/blog) for more examples and use cases for deploying to QuantCDN.
 
-## Deploying to Layer0
+## Deploying to Layer0 {#deploying-to-layer0}
 
 [Layer0](https://www.layer0.co) is an all-in-one platform to develop, deploy, preview, experiment on, monitor, and run your headless frontend. It is focused on large, dynamic websites and best-in-class performance through EdgeJS (a JavaScript-based Content Delivery Network), predictive prefetching, and performance monitoring. Layer0 offers a free tier. Get started in just a few minutes by following [Layer0's guide to deploying Docusaurus](https://docs.layer0.co/guides/docusaurus).
+
+## Deploying to Cloudflare Pages {#deploying-to-cloudflare-pages}
+
+[Cloudflare Pages](https://pages.cloudflare.com/) is a Jamstack platform for frontend developers to collaborate and deploy websites. Get started within a few minutes by following [this article](https://dev.to/apidev234/deploying-docusaurus-to-cloudflare-pages-565g).
diff --git a/website/versioned_docs/version-2.0.0-beta.15/docusaurus-core.md b/website/versioned_docs/version-2.0.0-beta.17/docusaurus-core.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/docusaurus-core.md
rename to website/versioned_docs/version-2.0.0-beta.17/docusaurus-core.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/creating-pages.md b/website/versioned_docs/version-2.0.0-beta.17/guides/creating-pages.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/creating-pages.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/creating-pages.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-create-doc.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-create-doc.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-create-doc.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-create-doc.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-introduction.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-introduction.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-introduction.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-introduction.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-markdown-features.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-markdown-features.mdx
similarity index 92%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-markdown-features.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-markdown-features.mdx
index fe2660b21250..40be16cb9e54 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-markdown-features.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-markdown-features.mdx
@@ -29,7 +29,7 @@ Reference to another [document in a subfolder](subfolder/doc3.md).
 
 :::tip
 
-It is better to use relative file paths links instead of relative links:
+Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits:
 
 - links will keep working on the GitHub interface
 - you can customize the document slugs without having to update all the links
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-multi-instance.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-multi-instance.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/docs-multi-instance.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/docs-multi-instance.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/autogenerated.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/autogenerated.md
similarity index 91%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/autogenerated.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/autogenerated.md
index 4282e02c11a4..807de81571de 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/autogenerated.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/autogenerated.md
@@ -194,6 +194,19 @@ Naming your introductory document `README.md` makes it show up when browsing the
 
 :::
 
+:::tip
+
+If a folder only has one index page, it will be turned into a link instead of a category. This is useful for **asset collocation**:
+
+```
+some-doc
+├── index.md
+├── img1.png
+└── img2.png
+```
+
+:::
+
 <details>
 
 <summary>Customizing category index matching</summary>
@@ -292,9 +305,9 @@ function isCategoryIndex({fileName, directories}) {
 
 ## Autogenerated sidebar metadata {#autogenerated-sidebar-metadata}
 
-For hand-written sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item, because, by default, items within a sidebar slice will be generated in **alphabetical order** (using files and folders names).
+For handwritten sidebar definitions, you would provide metadata to sidebar items through `sidebars.js`; for autogenerated, Docusaurus would read them from the item's respective file. In addition, you may want to adjust the relative position of each item because, by default, items within a sidebar slice will be generated in **alphabetical order** (using file and folder names).
 
-**For docs**: use additional front matter. The `label` and `className` attributes now become `sidebar_label` and `sidebar_class_name`, while there's an additional `sidebar_position` front matter.
+**For docs**: use additional front matter. The `label`, `className`, and `customProps` attributes are declared in front matter as `sidebar_label`, `sidebar_class_name`, and `sidebar_custom_props`, respectively. Position can be specified in the same way, via `sidebar_position` front matter.
 
 ```md title="docs/tutorials/tutorial-easy.md"
 ---
@@ -352,6 +365,8 @@ If the `link` is explicitly specified, Docusaurus will not apply any [default co
 
 The doc links can be specified relatively, e.g. if the category is generated with the `guides` directory, `"link": {"type": "doc", "id": "intro"}` will be resolved to the ID `guides/intro`, only falling back to `intro` if a doc with the former ID doesn't exist.
 
+You can also use `link: null` to opt out of default conventions and not generate any category index page.
+
 :::
 
 :::info
@@ -360,7 +375,7 @@ The position metadata is only used **within a sidebar slice**: Docusaurus does n
 
 :::
 
-## Using number prefixes
+## Using number prefixes {#using-number-prefixes}
 
 A simple way to order an autogenerated sidebar is to prefix docs and folders by number prefixes, which also makes them appear in the file system in the same order when sorted by file name:
 
@@ -396,7 +411,7 @@ Updating a number prefix can be annoying, as it can require **updating multiple
 
 :::
 
-## Customize the sidebar items generator
+## Customize the sidebar items generator {#customize-the-sidebar-items-generator}
 
 You can provide a custom `sidebarItemsGenerator` function in the docs plugin (or preset) config:
 
@@ -413,6 +428,7 @@ module.exports = {
           item,
           version,
           docs,
+          categoriesMetadata,
           isCategoryIndex,
         }) {
           // Example: return an hardcoded list of static sidebar items
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/index.md
similarity index 88%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/index.md
index a839f6ba8e2c..9634f4853cac 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/index.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/index.md
@@ -117,7 +117,7 @@ type SidebarsFile = {
 };
 ```
 
-## Theme configuration
+## Theme configuration {#theme-configuration}
 
 ### Hideable sidebar {#hideable-sidebar}
 
@@ -133,7 +133,7 @@ module.exports = {
 };
 ```
 
-### Auto-collapse sidebar categories
+### Auto-collapse sidebar categories {#auto-collapse-sidebar-categories}
 
 The `themeConfig.autoCollapseSidebarCategories` option would collapse all sibling categories when expanding one category. This saves the user from having too many categories open and helps them focus on the selected section.
 
@@ -160,6 +160,28 @@ To pass in custom props to a swizzled sidebar item, add the optional `customProp
 };
 ```
 
+## Sidebar Breadcrumbs {#sidebar-breadcrumbs}
+
+By default, breadcrumbs are rendered at the top, using the "sidebar path" of the current page.
+
+This behavior can be disabled with plugin options:
+
+```js title="docusaurus.config.js"
+module.exports = {
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          // highlight-next-line
+          breadcrumbs: false,
+        },
+      },
+    ],
+  ],
+};
+```
+
 ## Complex sidebars example {#complex-sidebars-example}
 
 A real-world example from the Docusaurus site:
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/items.md
similarity index 75%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/items.md
index 30e9471204c0..04faf577a7e7 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/items.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/items.md
@@ -5,12 +5,18 @@ slug: /sidebar/items
 
 # Sidebar items
 
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
 We have introduced three types of item types in the example in the previous section: `doc`, `category`, and `link`, whose usages are fairly intuitive. We will formally introduce their APIs. There's also a fourth type: `autogenerated`, which we will explain in detail later.
 
 - **[Doc](#sidebar-item-doc)**: link to a doc page, associating it with the sidebar
 - **[Link](#sidebar-item-link)**: link to any internal or external page
 - **[Category](#sidebar-item-category)**: creates a dropdown of sidebar items
 - **[Autogenerated](autogenerated.md)**: generate a sidebar slice automatically
+- **[HTML](#sidebar-item-html)**: renders pure HTML in the item's position
 - **[\*Ref](multiple-sidebars.md#sidebar-item-ref)**: link to a doc page, without making the item take part in navigation generation
 
 ## Doc: link to a doc {#sidebar-item-doc}
@@ -25,6 +31,7 @@ type SidebarItemDoc =
       id: string;
       label: string; // Sidebar label text
       className?: string; // Class name for sidebar label
+      customProps?: Record<string, unknown>; // Custom props
     }
 
   // Shorthand syntax
@@ -40,20 +47,20 @@ module.exports = {
     // highlight-start
     {
       type: 'doc',
-      id: 'doc1', // document id
+      id: 'doc1', // document ID
       label: 'Getting started', // sidebar label
     },
     // highlight-end
 
     // Shorthand syntax:
     // highlight-start
-    'doc2', // document id
+    'doc2', // document ID
     // highlight-end
   ],
 };
 ```
 
-If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item.
+If you use the doc shorthand or [autogenerated](#sidebar-item-autogenerated) sidebar, you would lose the ability to customize the sidebar label through item definition. You can, however, use the `sidebar_label` markdown front matter within that doc, which has higher precedence over the `label` key in the sidebar item. Similarly, you can use `sidebar_custom_props` to declare custom metadata for a doc page.
 
 :::note
 
@@ -61,6 +68,12 @@ A `doc` item sets an [implicit sidebar association](#sidebar-association). Don't
 
 :::
 
+:::tip
+
+Sidebar custom props is a useful way to propagate arbitrary doc metadata to the client side, so you can get additional information when using any doc-related hook that fetches a doc object.
+
+:::
+
 ## Link: link to any page {#sidebar-item-link}
 
 Use the `link` type to link to any page (internal or external) that is not a doc.
@@ -100,6 +113,55 @@ module.exports = {
 };
 ```
 
+## HTML: render custom markup {#sidebar-item-html}
+
+Use the `html` type to render custom HTML within the item's `<li>` tag.
+
+This can be useful for inserting custom items such as dividers, section titles, ads, and images.
+
+```ts
+type SidebarItemHtml = {
+  type: 'html';
+  value: string;
+  defaultStyle?: boolean; // Use default menu item styles
+  className?: string;
+};
+```
+
+Example:
+
+```js title="sidebars.js"
+module.exports = {
+  myHtmlSidebar: [
+    // highlight-start
+    {
+      type: 'html',
+      value: '<img src="sponsor.png" alt="Sponsor" />', // The HTML to be rendered
+      defaultStyle: true, // Use the default menu item styling
+    },
+    // highlight-end
+  ],
+};
+```
+
+:::tip
+
+The menu item is already wrapped in an `<li>` tag, so if your custom item is simple, such as a title, just supply a string as the value and use the `className` property to style it:
+
+```js title="sidebars.js"
+module.exports = {
+  myHtmlSidebar: [
+    {
+      type: 'html',
+      value: 'Core concepts',
+      className: 'sidebar-title',
+    },
+  ],
+};
+```
+
+:::
+
 ## Category: create a hierarchy {#sidebar-item-category}
 
 Use the `category` type to create a hierarchy of sidebar items.
@@ -207,6 +269,8 @@ module.exports = {
         title: 'Docusaurus Guides',
         description: 'Learn about the most important Docusaurus concepts!',
         slug: '/category/docusaurus-guides',
+        keywords: ['guides'],
+        image: '/img/docusaurus.png',
       },
       // highlight-end
       items: ['pages', 'docs', 'blog', 'search'],
@@ -223,7 +287,7 @@ Use `generated-index` links as a quick way to get an introductory document.
 
 :::
 
-#### Embedding generated index in doc page
+#### Embedding generated index in doc page {#embedding-generated-index-in-doc-page}
 
 You can embed the generated cards list in a normal doc page as well, as long as the doc is used as a category index page. To do so, you need to use the `DocCardList` component, paired with the `useCurrentSidebarCategory` hook.
 
@@ -340,20 +404,38 @@ You can express typical sidebar items without much customization more concisely
 
 An item with type `doc` can be simply a string representing its ID:
 
-```js
-// =================
-// This item:
-// =================
-{
-  type: 'doc',
-  id: 'myDoc',
+<Tabs>
+<TabItem value="Longhand">
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+    // highlight-start
+    {
+      type: 'doc',
+      id: 'myDoc',
+    },
+    // highlight-end
+  ],
+};
+```
+
+</TabItem>
+<TabItem value="Shorthand">
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+    // highlight-start
+    'myDoc',
+    // highlight-end
+  ],
 };
-// =================
-// Is equivalent to:
-// =================
-'myDoc';
 ```
 
+</TabItem>
+</Tabs>
+
 So it's possible to simplify the example above to:
 
 ```js title="sidebars.js"
@@ -390,23 +472,41 @@ module.exports = {
 
 A category item can be represented by an object whose key is its label, and the value is an array of subitems.
 
-```js
-// ===================
-// This item:
-// ===================
-{
-  type: 'category',
-  label: 'Getting started',
-  items: ['doc1', 'doc2'],
+<Tabs>
+<TabItem value="Longhand">
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+    // highlight-start
+    {
+      type: 'category',
+      label: 'Getting started',
+      items: ['doc1', 'doc2'],
+    },
+    // highlight-end
+  ],
 };
-// ===================
-// Is equivalent to:
-// ===================
-{
-  'Getting started': ['doc1', 'doc2'],
+```
+
+</TabItem>
+<TabItem value="Shorthand">
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+    // highlight-start
+    {
+      'Getting started': ['doc1', 'doc2'],
+    },
+    // highlight-end
+  ],
 };
 ```
 
+</TabItem>
+</Tabs>
+
 This permits us to simplify that example to:
 
 ```js title="sidebars.js"
@@ -450,3 +550,42 @@ module.exports = {
 ```
 
 Note how the two consecutive category shorthands are compressed into one object with two entries. This syntax generates a **sidebar slice**: you shouldn't see that object as one bulk item—this object is unwrapped, with each entry becoming a separate item, and they spliced together with the rest of the items (in this case, the "Learn more" link) to form the final sidebar level. Sidebar slices are also important when discussing [autogenerated sidebars](autogenerated.md).
+
+Wherever you have an array of items that is reduced to one category shorthand, you can omit that enclosing array as well.
+
+<Tabs>
+<TabItem value="Before">
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: [
+    {
+      'Getting started': ['doc1'],
+      Docusaurus: [
+        {
+          'Basic guides': ['doc2', 'doc3'],
+          'Advanced guides': ['doc4', 'doc5'],
+        },
+      ],
+    },
+  ],
+};
+```
+
+</TabItem>
+<TabItem value="After">
+
+```js title="sidebars.js"
+module.exports = {
+  sidebar: {
+    'Getting started': ['doc1'],
+    Docusaurus: {
+      'Basic guides': ['doc2', 'doc3'],
+      'Advanced guides': ['doc4', 'doc5'],
+    },
+  },
+};
+```
+
+</TabItem>
+</Tabs>
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/multiple-sidebars.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/multiple-sidebars.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/sidebar/multiple-sidebars.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/sidebar/multiple-sidebars.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/versioning.md b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/versioning.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/docs/versioning.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/docs/versioning.md
index 761c9e7fb6f8..0e519937c721 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/docs/versioning.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/docs/versioning.md
@@ -21,7 +21,7 @@ Most of the time, you don't need versioning as it will just increase your build
 
 To better understand how versioning works and see if it suits your needs, you can read on below.
 
-## Overview
+## Overview {#overview}
 
 A typical versioned doc site looks like below:
 
@@ -67,7 +67,7 @@ By default, the `current` docs version is labeled as `Next` and hosted under `/d
 
 :::
 
-### Terminology
+### Terminology {#terminology}
 
 Note the terminology we use here.
 
@@ -80,7 +80,7 @@ Note the terminology we use here.
 
 Current version is defined by the **file system location**, while latest version is defined by the **the navigation behavior**. They may or may not be the same version! (And the default configuration, as shown in the table above, would treat them as different: current version at `/docs/next` and latest at `/docs`.)
 
-## Tutorials
+## Tutorials {#tutorials}
 
 ### Tagging a new version {#tagging-a-new-version}
 
@@ -157,7 +157,7 @@ Example:
 2. Delete the versioned docs directory. Example: `versioned_docs/version-1.8.0`.
 3. Delete the versioned sidebars file. Example: `versioned_sidebars/version-1.8.0-sidebars.json`.
 
-## Configuring versioning behavior
+## Configuring versioning behavior {#configuring-versioning-behavior}
 
 The "current" version is the version name for the `./docs` folder. There are different ways to manage versioning, but two very common patterns are:
 
@@ -207,7 +207,7 @@ We offer these plugin options to customize versioning behavior:
 
 See [docs plugin configuration](../../api/plugins/plugin-content-docs.md#configuration) for more details.
 
-## Navbar items
+## Navbar items {#navbar-items}
 
 We offer several navbar items to help you quickly set up navigation without worrying about versioned routes.
 
@@ -249,7 +249,7 @@ Don't use relative paths import within the docs. Because when we cut a version t
 + import Foo from '@site/src/components/Foo';
 ```
 
-### Link docs by file paths
+### Link docs by file paths {#link-docs-by-file-paths}
 
 Refer to other docs by relative file paths with the `.md` extension, so that Docusaurus can rewrite them to actual URL paths during building. Files will be linked to the correct corresponding version.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/_markdown-partial-example.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/_markdown-partial-example.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/_markdown-partial-example.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/_markdown-partial-example.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-admonitions.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-admonitions.mdx
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-admonitions.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-admonitions.mdx
index 5925156d8b5b..365641ab2504 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-admonitions.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-admonitions.mdx
@@ -124,7 +124,7 @@ Some **content** with _markdown_ `syntax`.
 
 </BrowserWindow>
 
-## Admonitions with MDX
+## Admonitions with MDX {#admonitions-with-mdx}
 
 You can use MDX inside admonitions too!
 
@@ -160,7 +160,7 @@ import TabItem from '@theme/TabItem';
 
 </BrowserWindow>
 
-## Usage in JSX
+## Usage in JSX {#usage-in-jsx}
 
 Outside of Markdown, you can use the `@theme/Admonition` component to get the same output.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-assets.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-assets.mdx
similarity index 83%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-assets.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-assets.mdx
index de1d18905a05..32194db3291e 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-assets.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-assets.mdx
@@ -87,6 +87,12 @@ or
 
 </BrowserWindow>
 
+:::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.
+
+:::
+
 ## Inline SVGs {#inline-svgs}
 
 Docusaurus supports inlining SVGs out of the box.
@@ -114,11 +120,11 @@ import DocusaurusSvg from './docusaurus.svg';
 ```
 
 ```css
-html[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
+[data-theme='light'] .themedDocusaurus [fill='#FFFF50'] {
   fill: greenyellow;
 }
 
-html[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
+[data-theme='dark'] .themedDocusaurus [fill='#FFFF50'] {
   fill: seagreen;
 }
 ```
@@ -160,15 +166,15 @@ import ThemedImage from '@theme/ThemedImage';
 </BrowserWindow>
 ```
 
-### GitHub-style themed images
+### GitHub-style themed images {#github-style-themed-images}
 
 GitHub uses its own [image theming approach](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/) with path fragments, which you can easily implement yourself.
 
 To toggle the visibility of an image using the path fragment (for GitHub, it's `#gh-dark-mode-only` and `#gh-light-mode-only`), add the following to your custom CSS (you can also use your own suffix if you don't want to be coupled to GitHub):
 
 ```css title="src/css/custom.css"
-html[data-theme='light'] img[src$='#gh-dark-mode-only'],
-html[data-theme='dark'] img[src$='#gh-light-mode-only'] {
+[data-theme='light'] img[src$='#gh-dark-mode-only'],
+[data-theme='dark'] img[src$='#gh-light-mode-only'] {
   display: none;
 }
 ```
@@ -191,7 +197,15 @@ If a Markdown link or image has an absolute path, the path will be seen as a fil
 ![An image from the static](/img/docusaurus.png)
 ```
 
-Docusaurus will try to look for it in both `static/img/docusaurus.png` and `public/img/docusaurus.png`. The link will then be converted to a `require` call instead of staying as a URL. This is desirable in two regards:
+Docusaurus will try to look for it in both `static/img/docusaurus.png` and `public/img/docusaurus.png`. The link will then be converted to a `require()` call instead of staying as a URL. This is desirable in two regards:
 
 1. You don't have to worry about the base URL, which Docusaurus will take care of when serving the asset;
 2. The image enters Webpack's build pipeline and its name will be appended by a hash, which enables browsers to aggressively cache the image and improves your site's performance.
+
+If you intend to write URLs, you can use the `pathname://` protocol to disable automatic asset linking.
+
+```md
+![banner](pathname:///img/docusaurus-asset-example-banner.png)
+```
+
+This link will be generated as `<img src="/img/docusaurus-asset-example-banner.png" alt="banner" />`, without any processing or file existence checking.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-code-blocks.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-code-blocks.mdx
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-code-blocks.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-code-blocks.mdx
index b57c25dcddd6..7934b6ebaafb 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-code-blocks.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-code-blocks.mdx
@@ -197,13 +197,13 @@ To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class t
 }
 
 /* If you have a different syntax highlighting theme for dark mode. */
-html[data-theme='dark'] .docusaurus-highlight-code-line {
+[data-theme='dark'] .docusaurus-highlight-code-line {
   /* Color which works with dark mode syntax highlighting theme */
   background-color: rgb(100, 100, 100);
 }
 ```
 
-### Highlighting with metadata string
+### Highlighting with metadata string {#highlighting-with-metadata-string}
 
 You can also specify highlighted line ranges within the language meta string (leave a space after the language). To highlight multiple lines, separate the line numbers by commas or use the range syntax to select a chunk of lines. This feature uses the `parse-number-range` library and you can find [more syntax](https://www.npmjs.com/package/parse-numeric-range) on their project details.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-head-metadata.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-head-metadata.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-head-metadata.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-head-metadata.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-headings.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-headings.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-headings.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-headings.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-inline-toc.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-inline-toc.mdx
similarity index 59%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-inline-toc.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-inline-toc.mdx
index bfdc6c1a6d4b..4a48251ac4d0 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-inline-toc.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-inline-toc.mdx
@@ -35,30 +35,33 @@ import TOCInline from '@theme/TOCInline';
 
 ## Custom table of contents {#custom-table-of-contents}
 
-The `toc` props is just a list of table of contents items:
+The `toc` prop is just a list of heading items:
 
 ```ts
 type TOCItem = {
   value: string;
   id: string;
-  children: TOCItem[];
   level: number;
 };
 ```
 
-You can create this TOC tree manually, or derive a new TOC tree from the `toc` variable:
+Note that the `toc` global is a flat array, so you can easily cut out unwanted nodes or insert extra nodes, and create a new TOC tree.
 
 ```jsx
 import TOCInline from '@theme/TOCInline';
 
 <TOCInline
-  toc={
-    // Only show 3th and 5th top-level heading
-    [toc[2], toc[4]]
-  }
+  // Only show h2 and h4 headings
+  toc={toc.filter((node) => node.level === 2 || node.level === 4)}
 />;
 ```
 
+```mdx-code-block
+<BrowserWindow>
+<TOCInline toc={toc.filter((node) => node.level === 2 || node.level === 4)} />
+</BrowserWindow>
+```
+
 ---
 
 :::caution
@@ -75,14 +78,32 @@ Lorem ipsum
 
 Lorem ipsum
 
+#### Example subsubsection 1 a I
+
+#### Example subsubsection 1 a II
+
+#### Example subsubsection 1 a III
+
 ### Example Subsection 1 b {#example-subsection-1-b}
 
 Lorem ipsum
 
+#### Example subsubsection 1 b I
+
+#### Example subsubsection 1 b II
+
+#### Example subsubsection 1 b III
+
 ### Example Subsection 1 c {#example-subsection-1-c}
 
 Lorem ipsum
 
+#### Example subsubsection 1 c I
+
+#### Example subsubsection 1 c II
+
+#### Example subsubsection 1 c III
+
 ## Example Section 2 {#example-section-2}
 
 Lorem ipsum
@@ -91,14 +112,32 @@ Lorem ipsum
 
 Lorem ipsum
 
+#### Example subsubsection 2 a I
+
+#### Example subsubsection 2 a II
+
+#### Example subsubsection 2 a III
+
 ### Example Subsection 2 b {#example-subsection-2-b}
 
 Lorem ipsum
 
+#### Example subsubsection 2 b I
+
+#### Example subsubsection 2 b II
+
+#### Example subsubsection 2 b III
+
 ### Example Subsection 2 c {#example-subsection-2-c}
 
 Lorem ipsum
 
+#### Example subsubsection 2 c I
+
+#### Example subsubsection 2 c II
+
+#### Example subsubsection 2 c III
+
 ## Example Section 3 {#example-section-3}
 
 Lorem ipsum
@@ -107,10 +146,28 @@ Lorem ipsum
 
 Lorem ipsum
 
+#### Example subsubsection 3 a I
+
+#### Example subsubsection 3 a II
+
+#### Example subsubsection 3 a III
+
 ### Example Subsection 3 b {#example-subsection-3-b}
 
 Lorem ipsum
 
+#### Example subsubsection 3 b I
+
+#### Example subsubsection 3 b II
+
+#### Example subsubsection 3 b III
+
 ### Example Subsection 3 c {#example-subsection-3-c}
 
 Lorem ipsum
+
+#### Example subsubsection 3 c I
+
+#### Example subsubsection 3 c II
+
+#### Example subsubsection 3 c III
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-intro.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-intro.mdx
similarity index 97%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-intro.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-intro.mdx
index 0f5c99cca3f6..77bb79d0fda1 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-intro.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-intro.mdx
@@ -18,7 +18,7 @@ This section assumes you are using the official Docusaurus content plugins.
 
 :::
 
-## Standard features
+## Standard features {#standard-features}
 
 Markdown is a syntax that enables you to write formatted content in a readable syntax.
 
@@ -44,7 +44,7 @@ Hello world message with some **bold** text, some _italic_ text and a [link](/)
 </BrowserWindow>
 ```
 
-## Quotes
+## Quotes {#quotes}
 
 Markdown quotes are beautifully styled:
 
@@ -62,7 +62,7 @@ Markdown quotes are beautifully styled:
 
 </BrowserWindow>
 
-## Details
+## Details {#details}
 
 Markdown can embed HTML elements, and [`details`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/details) HTML elements are beautifully styled:
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-math-equations.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-math-equations.mdx
similarity index 81%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-math-equations.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-math-equations.mdx
index f329431be21c..d785f3d027c0 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-math-equations.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-math-equations.mdx
@@ -9,11 +9,11 @@ import BrowserWindow from '@site/src/components/BrowserWindow';
 
 Mathematical equations can be rendered using [KaTeX](https://katex.org).
 
-## Usage
+## Usage {#usage}
 
 Please read [KaTeX](https://katex.org) documentation for more details.
 
-### Inline
+### Inline {#inline}
 
 Write inline math equations by wrapping LaTeX equations between `$`:
 
@@ -29,7 +29,7 @@ Let $f\colon[a,b] \to \R$ be Riemann integrable. Let $F\colon[a,b]\to\R$ be $F(x
 
 </BrowserWindow>
 
-### Blocks
+### Blocks {#blocks}
 
 For equation block or display mode, use line breaks and `$$`:
 
@@ -47,7 +47,7 @@ $$
 
 </BrowserWindow>
 
-## Configuration
+## Configuration {#configuration}
 
 To enable KaTeX, you need to install `remark-math` and `rehype-katex` plugins.
 
@@ -128,7 +128,22 @@ module.exports = {
 };
 ```
 
-## Upgrading rehype-katex beyond recommended version
+## 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`).
+
+```js title="docusaurus.config.js"
+module.exports = {
+  stylesheets: [
+    {
+      href: '/katex/katex.min.css',
+      type: 'text/css',
+    },
+  ],
+};
+```
+
+## Upgrading rehype-katex beyond recommended version {#upgrading-rehype-katex-beyond-recommended-version}
 
 :::tip
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-plugins.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-plugins.mdx
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-plugins.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-plugins.mdx
index 031f2db4fe97..8033833585b7 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-plugins.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-plugins.mdx
@@ -114,7 +114,7 @@ module.exports = {
 
 You should check your plugin's documentation for the options it supports.
 
-## Creating new rehype/remark plugins
+## Creating new rehype/remark plugins {#creating-new-rehyperemark-plugins}
 
 If there isn't an existing package that satisfies your customization need, you can create your own MDX plugin.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-react.mdx
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-react.mdx
index b58fe8172cd0..be6f0018fa05 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-react.mdx
@@ -87,7 +87,7 @@ In addition, MDX is not [100% compatible with CommonMark](https://github.com/fac
 
 :::
 
-### Importing components
+### Importing components {#importing-components}
 
 You can also import your own components defined in other files or third-party components installed via npm.
 
@@ -133,7 +133,7 @@ import Highlight from '@site/src/components/Highlight';
 
 Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
 
-### Markdown and JSX interoperability
+### 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.
 
@@ -419,7 +419,7 @@ The table of contents does not currently contain the imported Markdown headings.
 
 :::
 
-## Available exports
+## Available exports {#available-exports}
 
 Within the MDX page, the following variables are available as globals:
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.module.css b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-react.module.css
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-react.module.css
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-react.module.css
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-tabs-styles.module.css b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-tabs-styles.module.css
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-tabs-styles.module.css
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-tabs-styles.module.css
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-tabs.mdx b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-tabs.mdx
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-tabs.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-tabs.mdx
index 3517311da68d..55ce040ead00 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/guides/markdown-features/markdown-features-tabs.mdx
+++ b/website/versioned_docs/version-2.0.0-beta.17/guides/markdown-features/markdown-features-tabs.mdx
@@ -128,7 +128,7 @@ It is possible to only render the default tab with `<Tabs lazy />`.
 
 :::
 
-## Displaying a default tab
+## Displaying a default tab {#displaying-a-default-tab}
 
 The first tab is displayed by default, and to override this behavior, you can specify a default tab by adding `default` to one of the tab items. You can also set the `defaultValue` prop of the `Tabs` component to the label value of your choice. For example, in the example above, either setting `default` for the `value="apple"` tab or setting `defaultValue="apple"` for the tabs forces the "Apple" tab to be open by default.
 
@@ -248,7 +248,7 @@ You might want to customize the appearance of a certain set of tabs. You can pas
 </BrowserWindow>
 ```
 
-### Customizing tab headings
+### Customizing tab headings {#customizing-tab-headings}
 
 You can also customize each tab heading independently by using the `attributes` field. The extra props can be passed to the headings either through the `values` prop in `Tabs`, or props of each `TabItem`—in the same way as you declare `label`.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/guides/whats-next.md b/website/versioned_docs/version-2.0.0-beta.17/guides/whats-next.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/guides/whats-next.md
rename to website/versioned_docs/version-2.0.0-beta.17/guides/whats-next.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-crowdin.mdx b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-crowdin.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-crowdin.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-crowdin.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-git.md b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-git.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-git.md
rename to website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-git.md
index 6f4188cce5f9..12c8f157995f 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-git.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-git.md
@@ -30,7 +30,7 @@ Refer to the [Docusaurus i18n RFC](https://github.com/facebook/docusaurus/issues
 
 :::
 
-## Initialization
+## Initialization {#initialization}
 
 This is a walk-through of using Git to translate a newly initialized English Docusaurus website into French, and assume you already followed the [i18n tutorial](./i18n-tutorial.md).
 
@@ -145,7 +145,7 @@ npm run build -- --locale fr
 
 Follow the same process for each locale you need to support.
 
-## Maintenance
+## Maintenance {#maintenance}
 
 Keeping translated files **consistent** with the originals **can be challenging**, in particular for Markdown documents.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-introduction.md b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-introduction.md
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-introduction.md
rename to website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-introduction.md
index ae5ef8ca7478..610e8304175d 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-introduction.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-introduction.md
@@ -85,7 +85,7 @@ The choice was made for 2 reasons:
 - **Description attribute**: to help translators with additional context
 - **Widely supported**: [Chrome extensions](https://developer.chrome.com/docs/extensions/mv2/i18n-messages/), [Crowdin](https://support.crowdin.com/file-formats/chrome-json/), [Transifex](https://docs.transifex.com/formats/chrome-json), [Phrase](https://help.phrase.com/help/chrome-json-messages), [Applanga](https://www.applanga.com/docs/formats/chrome_i18n_json), etc.
 
-#### Data files
+#### Data files {#data-files}
 
 Some plugins may read from external data files that are localized as a whole. For example, the blog plugin uses an [`authors.yml`](../blog.mdx#global-authors) file that can be translated by creating a copy under `i18n/[locale]/docusaurus-plugin-content-blog/authors.yml`.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-tutorial.md b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-tutorial.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-tutorial.md
rename to website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-tutorial.md
index a3237af1739b..477b89d5afa9 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/i18n/i18n-tutorial.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/i18n/i18n-tutorial.md
@@ -102,7 +102,7 @@ After copying files around, restart your site with `npm run start -- --locale fr
 
 :::
 
-### Translate your React code
+### Translate your React code {#translate-your-react-code}
 
 For any React code you've written yourself: React pages, React components, etc., you will use the [**translation APIs**](../docusaurus-core.md#translate).
 
@@ -258,7 +258,7 @@ You can see the calls to the translation APIs as purely _markers_ that tell Docu
 
 :::
 
-### Translate plugin data
+### Translate plugin data {#translate-plugin-data}
 
 JSON translation files are used for everything that is interspersed in your code:
 
@@ -450,7 +450,7 @@ It is also possible to deploy each locale as a separate subdomain, assemble the
 - Deploy your site as `fr.docusaurus.io`
 - Configure a CDN to serve it from `docusaurus.io/fr`
 
-## Managing translations
+## Managing translations {#managing-translations}
 
 Docusaurus doesn't care about how you manage your translations: all it needs is that all translation files (JSON, Markdown, or other data files) are available in the file system during building. However, as site creators, you would need to consider how translations are managed so your translation contributors could collaborate well.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/installation.md b/website/versioned_docs/version-2.0.0-beta.17/installation.md
similarity index 83%
rename from website/versioned_docs/version-2.0.0-beta.15/installation.md
rename to website/versioned_docs/version-2.0.0-beta.17/installation.md
index 8331f9c26ed9..0a79f9b3f7cb 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/installation.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/installation.md
@@ -3,6 +3,11 @@ id: installation
 title: Installation
 ---
 
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+```
+
 Docusaurus is essentially a set of npm [packages](https://github.com/facebook/docusaurus/tree/main/packages).
 
 :::tip
@@ -17,7 +22,6 @@ Use **[docusaurus.new](https://docusaurus.new)** to test Docusaurus immediately
 
 - [Node.js](https://nodejs.org/en/download/) version >= 14 or above (which can be checked by running `node -v`). You can use [nvm](https://github.com/nvm-sh/nvm) for managing multiple Node versions on a single machine installed.
   - When installing Node.js, you are recommended to check all checkboxes related to dependencies.
-- [Yarn](https://yarnpkg.com/en/) version >= 1.5 (which can be checked by running `yarn --version`). Yarn is a performant package manager for JavaScript and replaces the `npm` client. It is not strictly necessary but highly encouraged.
 
 ## Scaffold project website {#scaffold-project-website}
 
@@ -33,9 +37,17 @@ Example:
 npx create-docusaurus@latest website classic
 ```
 
-If you do not specify `name` or `template`, it will prompt you for them. We recommend the `classic` template so that you can get started quickly, and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
+If you do not specify `name` or `template`, it will prompt you for them.
+
+We recommend the `classic` template so that you can get started quickly, and it contains features found in Docusaurus 1. The `classic` template contains `@docusaurus/preset-classic` which includes standard documentation, a blog, custom pages, and a CSS framework (with dark mode support). You can get up and running extremely quickly with the classic template and customize things later on when you have gained more familiarity with Docusaurus.
+
+The `template` also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory. If it's a git repository, you can also specify a cloning strategy. Run `npx create-docusaurus@latest --help` for more information.
 
-The `template` also accepts a git repo URL or a local file path, with the latter evaluated relative to the current working directory. The repo/folder content will be copied to the site directory.
+You can also use the template's TypeScript variant by passing the `--typescript` flag.
+
+```bash
+npx create-docusaurus@latest my-website classic --typescript
+```
 
 :::info FB-Only
 
@@ -47,16 +59,50 @@ npx create-docusaurus@latest my-website facebook
 
 :::
 
-If you want to skip installing dependencies, use the `--skip-install` option, like the following:
+<details>
+  <summary>Alternative installation commands</summary>
+
+You can also initialize a new project using your preferred project manager:
+
+````mdx-code-block
+<Tabs>
+<TabItem value="npm v6+">
 
 ```bash
-npx create-docusaurus@latest my-website classic --skip-install
+npm init docusaurus website classic
 ```
 
-You can also use the template's TypeScript variant by passing the `--typescript` flag.
+</TabItem>
+<TabItem value="yarn">
 
 ```bash
-npx create-docusaurus@latest my-website classic --typescript
+yarn create docusaurus website classic
+```
+
+</TabItem>
+<TabItem value="pnpm">
+
+```bash
+pnpm create docusaurus website classic
+```
+
+</TabItem>
+</Tabs>
+````
+
+</details>
+
+Docusaurus makes best efforts to select a package manager to install dependencies for you, based on the command you are using and the project you are in. You can override this behavior by using `--package-manager [npm/yarn/pnpm]`.
+
+```bash
+# Use Yarn to install dependencies even when the command is npx
+npx create-docusaurus@latest my-website classic --package-manager yarn
+```
+
+If you want to skip installing dependencies, use the `--skip-install` option.
+
+```bash
+npx create-docusaurus@latest my-website classic --skip-install
 ```
 
 ## Project structure {#project-structure}
@@ -100,7 +146,7 @@ my-website
 - `/package.json` - A Docusaurus website is a React app. You can install and use any npm packages you like in them
 - `/sidebar.js` - Used by the documentation to specify the order of documents in the sidebar
 
-### Monorepos
+### Monorepos {#monorepos}
 
 If you are using Docusaurus for documentation of an existing project, a monorepo may be the solution for you. Monorepos allow you to share dependencies between similar projects. For example, your website may use your local packages to showcase the latest features, instead of depending on a released version; your contributors can also conveniently update the docs as they implement features. An example monorepo folder structure is below:
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/introduction.md b/website/versioned_docs/version-2.0.0-beta.17/introduction.md
similarity index 94%
rename from website/versioned_docs/version-2.0.0-beta.15/introduction.md
rename to website/versioned_docs/version-2.0.0-beta.17/introduction.md
index 32c98c3f8397..36c26cfe1577 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/introduction.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/introduction.md
@@ -46,6 +46,22 @@ Or read the **[5-minute tutorial](https://tutorial.docusaurus.io)** online.
 
 :::
 
+## Docusaurus: Documentation Made Easy
+
+In this presentation at [Algolia Community Event](https://www.algolia.com/), [Meta Open Source team](https://opensource.facebook.com/) shared a brief walk-through of Docusaurus. They covered how to get started with the project, enable plugins, and set up functionalities like documentation and blogging.
+
+<div className="video-container">
+  <iframe
+    width="560"
+    height="315"
+    src="https://www.youtube.com/embed/Yhyx7otSksg"
+    title="Docusaurus: Documentation Made Easy"
+    frameBorder="0"
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+    allowFullScreen
+  />
+</div>
+
 ## Disclaimer {#disclaimer}
 
 Docusaurus v2 is **beta** but already quite stable and widely used.
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-automated.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-automated.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-automated.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-automated.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-manual.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-manual.md
similarity index 99%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-manual.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-manual.md
index 71d880ae6285..4f2a53cddf82 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-manual.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-manual.md
@@ -492,7 +492,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
 
 ### Footer {#footer}
 
-`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../advanced/swizzling.md#swizzling) it:
+`website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by Docusaurus, [swizzle](../swizzling.md) it:
 
 ```bash npm2yarn
 npm run swizzle @docusaurus/theme-classic Footer
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-overview.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-overview.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-overview.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-overview.md
index f65d3ae724f4..14e9b967694c 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-overview.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-overview.md
@@ -8,7 +8,7 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
 
 We try to make this as easy as possible, and provide a migration cli.
 
-## Main differences
+## Main differences {#main-differences}
 
 Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-translated-sites.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-translated-sites.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-translated-sites.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-translated-sites.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/migration/migration-versioned-sites.md b/website/versioned_docs/version-2.0.0-beta.17/migration/migration-versioned-sites.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/migration/migration-versioned-sites.md
rename to website/versioned_docs/version-2.0.0-beta.17/migration/migration-versioned-sites.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/playground.mdx b/website/versioned_docs/version-2.0.0-beta.17/playground.mdx
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/playground.mdx
rename to website/versioned_docs/version-2.0.0-beta.17/playground.mdx
diff --git a/website/versioned_docs/version-2.0.0-beta.15/search.md b/website/versioned_docs/version-2.0.0-beta.17/search.md
similarity index 95%
rename from website/versioned_docs/version-2.0.0-beta.15/search.md
rename to website/versioned_docs/version-2.0.0-beta.17/search.md
index f7632e87852c..d3b27ec96cab 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/search.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/search.md
@@ -107,6 +107,9 @@ module.exports = {
       // Optional: Algolia search parameters
       searchParameters: {},
 
+      // Optional: path for search page that enabled by default (`false` to disable it)
+      searchPagePath: 'search',
+
       //... other Algolia params
     },
     // highlight-end
@@ -118,13 +121,15 @@ module.exports = {
 
 The `searchParameters` option used to be named `algoliaOptions` in Docusaurus v1.
 
+Refer to its [official DocSearch documentation](https://docsearch.algolia.com/docs/api#searchparameters) for possible values.
+
 :::
 
 :::caution
 
-The search feature will not work reliably until Algolia crawls your site with the **search plugin enabled**.
+The search feature will not work reliably until Algolia crawls your site.
 
-If you are installing the Algolia plugin for the first time and want to ensure the search feature works before deploying it to production, you can ask the DocSearch team to trigger a crawl on a staging environment url or deploy preview.
+If search doesn't work after any significant change, please use the Algolia dashboard to **trigger a new crawl**.
 
 :::
 
@@ -173,7 +178,9 @@ module.exports = {
     // highlight-start
     algolia: {
       contextualSearch: false,
-      facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
+      searchParameters: {
+        facetFilters: ['language:en', ['filter1', 'filter2'], 'filter3'],
+      },
     },
     // highlight-end
   },
@@ -191,7 +198,7 @@ By default, DocSearch comes with a fine-tuned theme that was designed for access
 Still, you can reuse the [Infima CSS variables](styling-layout.md#styling-your-site-with-infima) from Docusaurus to style DocSearch by editing the `/src/css/custom.css` file.
 
 ```css title="/src/css/custom.css"
-html[data-theme='light'] .DocSearch {
+[data-theme='light'] .DocSearch {
   /* --docsearch-primary-color: var(--ifm-color-primary); */
   /* --docsearch-text-color: var(--ifm-font-color-base); */
   --docsearch-muted-color: var(--ifm-color-secondary-darkest);
@@ -209,7 +216,7 @@ html[data-theme='light'] .DocSearch {
   --docsearch-footer-background: var(--ifm-color-white);
 }
 
-html[data-theme='dark'] .DocSearch {
+[data-theme='dark'] .DocSearch {
   --docsearch-text-color: var(--ifm-font-color-base);
   --docsearch-muted-color: var(--ifm-color-secondary-darkest);
   --docsearch-container-background: rgba(47, 55, 69, 0.7);
diff --git a/website/versioned_docs/version-2.0.0-beta.15/seo.md b/website/versioned_docs/version-2.0.0-beta.17/seo.md
similarity index 100%
rename from website/versioned_docs/version-2.0.0-beta.15/seo.md
rename to website/versioned_docs/version-2.0.0-beta.17/seo.md
diff --git a/website/versioned_docs/version-2.0.0-beta.15/static-assets.md b/website/versioned_docs/version-2.0.0-beta.17/static-assets.md
similarity index 97%
rename from website/versioned_docs/version-2.0.0-beta.15/static-assets.md
rename to website/versioned_docs/version-2.0.0-beta.17/static-assets.md
index b666fddc79f2..ec2660c42d75 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/static-assets.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/static-assets.md
@@ -24,9 +24,9 @@ module.exports = {
 
 Now, all files in `public` as well as `static` will be copied to the build output.
 
-## Referencing your static asset
+## Referencing your static asset {#referencing-your-static-asset}
 
-### In JSX
+### In JSX {#in-jsx}
 
 In JSX, you can reference assets from the `static` folder in your code using absolute URLs, but this is not ideal because changing the site `baseUrl` will **break those links**. For the image `<img src="/img/docusaurus.png" />` served at `https://example.com/test`, the browser will try to resolve it from the URL root, i.e. as `https://example.com/img/docusaurus.png`, which will fail because it's actually served at `https://example.com/test/img/docusaurus.png`.
 
@@ -58,7 +58,7 @@ import DocusaurusLogoWithKeytar from '@site/static/img/docusaurus_keytar.svg';
 <DocusaurusLogoWithKeytar title="Docusaurus Logo" className="logo" />;
 ```
 
-### In Markdown
+### In Markdown {#in-markdown}
 
 In Markdown, you can stick to using absolute paths when writing links or images **in Markdown syntax** because Docusaurus handles them as `require` calls instead of URLs when parsing the Markdown. See [Markdown static assets](./guides/markdown-features/markdown-features-assets.mdx).
 
@@ -74,7 +74,7 @@ Docusaurus will only parse links that are in Markdown syntax. If your asset refe
 
 :::
 
-### In CSS
+### In CSS {#in-css}
 
 In CSS, the `url()` function is commonly used to reference assets like fonts and images. To reference a static asset, use absolute paths:
 
diff --git a/website/versioned_docs/version-2.0.0-beta.15/styling-layout.md b/website/versioned_docs/version-2.0.0-beta.17/styling-layout.md
similarity index 86%
rename from website/versioned_docs/version-2.0.0-beta.15/styling-layout.md
rename to website/versioned_docs/version-2.0.0-beta.17/styling-layout.md
index a21b41bd9d11..1431b1e1583b 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/styling-layout.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/styling-layout.md
@@ -8,7 +8,7 @@ import ColorGenerator from '@site/src/components/ColorGenerator';
 
 :::tip
 
-This section is focused on styling through stylesheets. If you find yourself needing to update the DOM structure, you can refer to [swizzling](./advanced/swizzling.md#swizzling).
+This section is focused on styling through stylesheets. For more advanced customizations (DOM structure, React code...), refer to the [swizzling guide](./swizzling.md).
 
 :::
 
@@ -60,13 +60,19 @@ function MyComponent() {
 
 If you want to add CSS to any element, you can open the DevTools in your browser to inspect its class names. Class names come in several kinds:
 
-- **Theme class names**. These class names are listed exhaustively in [the next subsection](#theme-class-names). They don't have any default properties. You should always prioritize targeting stable class names in your custom CSS.
-- **Infima class names**. These class names usually follow the [BEM convention](http://getbem.com/naming/) of `block__element--modifier`. They are usually stable but are still considered implementation details, so you should generally avoid targeting them. However, you can [modify Infima CSS variables](#styling-your-site-with-infima).
+- **Theme class names**. These class names are listed exhaustively in [the next subsection](#theme-class-names). They don't have any default properties. You should always prioritize targeting those stable class names in your custom CSS.
+- **Infima class names**. These class names are found in the classic theme and usually follow the [BEM convention](http://getbem.com/naming/) of `block__element--modifier`. They are usually stable but are still considered implementation details, so you should generally avoid targeting them. However, you can [modify Infima CSS variables](#styling-your-site-with-infima).
 - **CSS module class names**. These class names have a hash in production (`codeBlockContainer_RIuc`) and are appended with a long file path in development. They are considered implementation details and you should almost always avoid targeting them in your custom CSS. If you must, you can use an [attribute selector](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors) (`[class*='codeBlockContainer']`) that ignores the hash.
 
-### Theme Class Names
+### Theme Class Names {#theme-class-names}
 
-We provide some predefined CSS class names for global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.
+We provide some stable CSS class names for robust and maintainable global layout styling. These names are theme-agnostic and meant to be targeted by custom CSS.
+
+:::tip
+
+If you can't find a way to create a robust CSS selector, please [report your customization use-case](https://github.com/facebook/docusaurus/discussions/5468) and we will consider adding new class names.
+
+:::
 
 <details>
 
@@ -112,25 +118,25 @@ In light mode, the `<html>` element has a `data-theme="light"` attribute; and in
 
 ```css
 /* Overriding root Infima variables */
-html[data-theme='dark'] {
+[data-theme='dark'] {
   --ifm-color-primary: #4e89e8;
 }
 /* Styling one class specially in dark mode */
-html[data-theme='dark'] .purple-text {
+[data-theme='dark'] .purple-text {
   color: plum;
 }
 ```
 
 ### Mobile View {#mobile-view}
 
-Docusaurus uses `966px` as the cutoff between mobile screen width and desktop. If you want your layout to be different in the mobile view, you can use media queries.
+Docusaurus uses `996px` as the cutoff between mobile screen width and desktop. If you want your layout to be different in the mobile view, you can use media queries.
 
 ```css
 .banner {
   padding: 4rem;
 }
 /** In mobile view, reduce the padding */
-@media screen and (max-width: 966px) {
+@media screen and (max-width: 996px) {
   .heroBanner {
     padding: 2rem;
   }
diff --git a/website/versioned_docs/version-2.0.0-beta.17/swizzling.md b/website/versioned_docs/version-2.0.0-beta.17/swizzling.md
new file mode 100644
index 000000000000..d1cf3347a6ae
--- /dev/null
+++ b/website/versioned_docs/version-2.0.0-beta.17/swizzling.md
@@ -0,0 +1,324 @@
+---
+description: Customize your site's appearance through creating your own theme components
+---
+
+# Swizzling
+
+In this section, we will introduce how customization of layout is done in Docusaurus.
+
+> Déja vu...?
+
+This section is similar to [Styling and Layout](./styling-layout.md), but this time, we will write actual React code instead of playing with stylesheets. We will talk about a central concept in Docusaurus: **swizzling**, which allows **deeper site customizations**.
+
+In practice, swizzling permits to **swap a theme component with your own implementation**, and it comes in 2 patterns:
+
+- [**Ejecting**](#ejecting): creates a **copy** of the original theme component, which you can fully **customize**
+- [**Wrapping**](#wrapping): creates a **wrapper** around the original theme component, which you can **enhance**
+
+<details>
+
+<summary>Why is it called swizzling?</summary>
+
+**The name comes from Objective-C and Swift-UI**: [method swizzling](https://pspdfkit.com/blog/2019/swizzling-in-swift/) is the process of changing the implementation of an existing selector (method).
+
+**For Docusaurus, component swizzling means providing an alternative component that takes precedence over the component provided by the theme.**
+
+You can think of it as [Monkey Patching](https://en.wikipedia.org/wiki/Monkey_patch) for React components, enabling you to override the default implementation. Gatsby has a similar concept called [theme shadowing](https://www.gatsbyjs.com/docs/how-to/plugins-and-themes/shadowing/).
+
+To gain a deeper understanding of this, you have to understand [how theme components are resolved](./advanced/client.md#theme-aliases).
+
+</details>
+
+## Swizzling Process
+
+### Overview
+
+Docusaurus provides an convenient **interactive CLI** to swizzle components. You generally only need to remember the following command:
+
+```bash npm2yarn
+npm run swizzle
+```
+
+It will generate a new component your `src/theme` directory, which should look like this example:
+
+````mdx-code-block
+<Tabs>
+<TabItem value="Ejecting">
+
+```jsx title="src/theme/SomeComponent.js"
+import React from 'react';
+
+export default function SomeComponent(props) {
+  // You can fully customize this implementation
+  // including changing the JSX, CSS and React hooks
+  return (
+    <div className="some-class">
+      <h1>Some Component</h1>
+      <p>Some component implementation details</p>
+    </div>
+  );
+}
+```
+
+</TabItem>
+<TabItem value="Wrapping">
+
+```jsx title="src/theme/SomeComponent.js"
+import React from 'react';
+import SomeComponent from '@theme-original/SomeComponent';
+
+export default function SomeComponentWrapper(props) {
+  // You can enhance the original component,
+  // including adding extra props or JSX elements around it
+  return (
+    <>
+      <SomeComponent {...props} />
+    </>
+  );
+}
+```
+
+</TabItem>
+</Tabs>
+````
+
+To get an overview of all the themes and components available to swizzle, run:
+
+```bash npm2yarn
+npm run swizzle -- --list
+```
+
+Use `--help` to see all available CLI options, or refer to the reference [swizzle CLI documentation](./cli.md#docusaurus-swizzle).
+
+:::note
+
+After swizzling a component, **restart your dev server** in order for Docusaurus to know about the new component.
+
+:::
+
+:::warning Prefer staying on the safe side
+
+Be sure to understand [which components are **safe to swizzle**](#what-is-safe-to-swizzle). Some components are **internal implementation details** of a theme.
+
+:::
+
+:::info
+
+`docusaurus swizzle` is only an automated way to help you swizzle the component. You can also create the `src/theme/SomeComponent.js` file manually, and Docusaurus will [resolve it](./advanced/client.md#theme-aliases). There's no internal magic behind this command!
+
+:::
+
+### Ejecting {#ejecting}
+
+Ejecting a theme component is the process of **creating a copy** of the original theme component, which you can **fully customize and override**.
+
+To eject a theme component, use the swizzle CLI interactively, or with the `--eject` option:
+
+```bash npm2yarn
+npm run swizzle [theme name] [component name] -- --eject
+```
+
+An example:
+
+```bash npm2yarn
+npm run swizzle @docusaurus/theme-classic Footer -- --eject
+```
+
+This will copy the current `<Footer />` component's implementation to your site's `src/theme` directory. Docusaurus will now use this `<Footer>` component copy instead of the original one. You are now free to completely re-implement the `<Footer>` component.
+
+```jsx title="src/theme/SomeComponent.js"
+import React from 'react';
+
+export default function Footer(props) {
+  return (
+    <footer>
+      <h1>This is my custom site footer</h1>
+      <p>And it is very different from the original</p>
+    </footer>
+  );
+}
+```
+
+:::caution
+
+Ejecting an [**unsafe**](#what-is-safe-to-swizzle) component can sometimes lead to copying a large amount of internal code, which you now have to maintain yourself. It can make Docusaurus upgrades more difficult, as you will need to migrate your customizations if the props received or internal theme APIs used have changed.
+
+**Prefer [wrapping](#wrapping) whenever possible**: the amount of code to maintain is smaller.
+
+:::
+
+:::tip Re-swizzling
+
+To keep ejected components up-to-date after a Docusaurus upgrade, re-run the eject command and compare the changes with `git diff`. You are also recommended to write a brief comment at the top of the file explaining what changes you have made, so that you could more easily re-apply your changes after re-ejection.
+
+:::
+
+### Wrapping {#wrapping}
+
+Wrapping a theme component is the process of **creating a wrapper** around the original theme component, which you can **enhance**.
+
+To wrap a theme component, use the swizzle CLI interactively, or with the `--wrap` option:
+
+```bash npm2yarn
+npm run swizzle [theme name] [component name] -- --wrap
+```
+
+An example:
+
+```bash npm2yarn
+npm run swizzle @docusaurus/theme-classic Footer -- --wrap
+```
+
+This will create a wrapper in your site's `src/theme` directory. Docusaurus will now use the `<FooterWrapper>` component instead of the original one. You can now add customizations around the original component.
+
+```jsx title="src/theme/SomeComponent.js"
+import React from 'react';
+import Footer from '@theme-original/Footer';
+
+export default function FooterWrapper(props) {
+  return (
+    <>
+      <section>
+        <h2>Extra section</h2>
+        <p>This is an extra section that appears above the original footer</p>
+      </section>
+      <Footer {...props} />
+    </>
+  );
+}
+```
+
+<details>
+  <summary>What is this <code>@theme-original</code> thing?</summary>
+
+Docusaurus uses [theme aliases](./advanced/client.md#theme-aliases) to resolve the theme components to use. The newly created wrapper takes the `@theme/SomeComponent` alias. `@theme-original/SomeComponent` permits to import original component that the wrapper shadows without creating an infinite import loop where the wrapper imports itself.
+
+</details>
+
+:::tip
+
+Wrapping a theme is a great way to **add extra components around existing one** without [ejecting](#ejecting) it. For example, you can easily add a custom comment system under each blog post:
+
+```jsx title="src/theme/BlogPostItem.js"
+import React from 'react';
+import BlogPostItem from '@theme-original/BlogPostItem';
+import MyCustomCommentSystem from '@site/src/MyCustomCommentSystem';
+
+export default function BlogPostItemWrapper(props) {
+  return (
+    <>
+      <BlogPostItem {...props} />
+      <MyCustomCommentSystem />
+    </>
+  );
+}
+```
+
+:::
+
+## What is safe to swizzle? {#what-is-safe-to-swizzle}
+
+> With great power comes great responsibility
+
+Some theme components are **internal implementation details** of a theme. Docusaurus allows you to swizzle them, but it **might be risky**.
+
+<details>
+
+<summary>Why is it risky?</summary>
+
+Theme authors (including us) might have to update their theme over time: changing the component props, name, file system location, types... For example, consider a component that receives two props `name` and `age`, but after a refactor, it now receives a `person` prop with the above two properties. Your component, which still expects these two props, will render `undefined` instead.
+
+Moreover, internal components may simply disappear. If a component is called `Sidebar` and it's later renamed to `DocSidebar`, your swizzled component will be completely ignored.
+
+**Theme components marked as unsafe may change in a backward-incompatible way between theme minor versions.** When upgrading a theme (or Docusaurus), your customizations might **behave unexpectedly**, and can even **break your site**.
+
+</details>
+
+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**
+- **Forbidden**: the swizzle CLI will prevent you from swizzling this component, because it is not designed to be swizzled at all
+
+:::note
+
+Some components might be safe to wrap, but not safe to eject.
+
+:::
+
+:::info
+
+Don't be too **afraid to swizzle unsafe components**: just keep in mind that **breaking changes** might happen, and you might need to upgrade your customizations manually on minor version upgrades.
+
+:::
+
+:::note Report your use-case
+
+If you have a **strong use-case for swizzling an unsafe component**, please [**report it here**](https://github.com/facebook/docusaurus/discussions/5468) and we will work together to find a solution to make it safe.
+
+:::
+
+## Which component should I swizzle? {#which-component-should-i-swizzle}
+
+It is not always clear which component you should swizzle exactly to achieve the desired result. `@docusaurus/theme-classic`, which provides most of the theme components, has about [100 components](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme)!
+
+:::tip
+
+To print an overview of all the `@docusaurus/theme-classic` components:
+
+```bash npm2yarn
+npm run swizzle @docusaurus/theme-classic -- --list
+```
+
+:::
+
+You can follow these steps to locate the appropriate component to swizzle:
+
+1. **Component description.** Some components provide a short description, which is a good way to find the right one.
+2. **Component name.** Official theme components are semantically named, so you should be able to infer its function from the name. The swizzle CLI allows you to enter part of a component name to narrow down the available choices. For example, if you run `yarn swizzle @docusaurus/theme-classic`, and enter `Doc`, only the docs-related components will be listed.
+3. **Start with a higher-level component.** Components form a tree with some components importing others. Every route will be associated with one top-level component that the route will render (most of them listed in [Routing in content plugins](./advanced/routing.md#routing-in-content-plugins)). For example, all blog post pages have `@theme/BlogPostPage` as the topmost component. You can start with swizzling this component, and then go down the component tree to locate the component that renders just what you are targeting. Don't forget to unswizzle the rest by deleting the files after you've found the correct one, so you don't maintain too many components.
+4. **Read the [theme source code](https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-classic/src/theme)** and use search wisely.
+
+:::tip Just ask!
+
+If you still have no idea which component to swizzle to achieve the desired effect, you can reach out for help in one of our [support channels](/community/support).
+
+We also want to understand better your fanciest customization use-cases, so please [**report them**](https://github.com/facebook/docusaurus/discussions/5468).
+
+:::
+
+## Do I need to swizzle? {#do-i-need-to-swizzle}
+
+Swizzling ultimately means you have to maintain some additional React code that interact with Docusaurus internal APIs. If you can, think about the following alternatives when customizing your site:
+
+1. **Use CSS.** CSS rules and selectors can often help you achieve a decent degree of customization. Refer to [styling and layout](./styling-layout.md) for more details.
+2. **Use translations.** It may sound surprising, but translations are ultimately just a way to customize the text labels. For example, if your site's default language is `en`, you can still run `yarn write-translations -l en` and edit the `code.json` emitted. Refer to the [i18n tutorial](./i18n/i18n-tutorial.md) for more details.
+
+:::tip
+
+**The smaller, the better.** If swizzling is inevitable, prefer to swizzle only the relevant part and maintain as little code on your own as possible. Swizzling a small component often means less risk of **breaking changes** during upgrade.
+
+[Wrapping](#wrapping) is also a far safer alternative to [ejecting](#ejecting).
+
+:::
+
+## Wrapping your site with `<Root>` {#wrapper-your-site-with-root}
+
+The `<Root>` component is rendered at the **very top** of the React tree, above the theme `<Layout>`, and **never unmounts**. It is the perfect place to add stateful logic that should not be re-initialized across navigations (user authentication status, shopping card state...).
+
+Swizzle it **manually** by creating a file at `src/theme/Root.js`:
+
+```js title="src/theme/Root.js"
+import React from 'react';
+
+// Default implementation, that you can customize
+export default function Root({children}) {
+  return <>{children}</>;
+}
+```
+
+:::tip
+
+Use this component to render React Context providers.
+
+:::
diff --git a/website/versioned_docs/version-2.0.0-beta.15/typescript-support.md b/website/versioned_docs/version-2.0.0-beta.17/typescript-support.md
similarity index 89%
rename from website/versioned_docs/version-2.0.0-beta.15/typescript-support.md
rename to website/versioned_docs/version-2.0.0-beta.17/typescript-support.md
index 71cbb9797272..3f9e09716855 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/typescript-support.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/typescript-support.md
@@ -128,4 +128,4 @@ For themes that support TypeScript theme components, you can add the `--typescri
 npm run swizzle @docusaurus/theme-classic Footer -- --typescript
 ```
 
-At this moment, the only official Docusaurus theme that supports TypeScript theme components is `@docusaurus/theme-classic`. If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./api/plugin-methods/extend-infrastructure.md#getTypeScriptThemePath).
+All official Docusaurus themes support TypeScript theme components, including [`theme-classic`](./api/themes/theme-classic.md), [`theme-live-codeblock`](./api/themes/theme-live-codeblock.md), and [`theme-search-algolia`](./api/themes/theme-search-algolia.md). If you are a Docusaurus theme package author who wants to add TypeScript support, see the [Lifecycle APIs docs](./api/plugin-methods/extend-infrastructure.md#getTypeScriptThemePath).
diff --git a/website/versioned_docs/version-2.0.0-beta.15/using-plugins.md b/website/versioned_docs/version-2.0.0-beta.17/using-plugins.md
similarity index 98%
rename from website/versioned_docs/version-2.0.0-beta.15/using-plugins.md
rename to website/versioned_docs/version-2.0.0-beta.17/using-plugins.md
index b25b49d8dea6..ac47fa25feb2 100644
--- a/website/versioned_docs/version-2.0.0-beta.15/using-plugins.md
+++ b/website/versioned_docs/version-2.0.0-beta.17/using-plugins.md
@@ -112,9 +112,9 @@ At most one plugin instance can be the "default plugin instance", by omitting th
 
 :::
 
-## Using themes
+## Using themes {#using-themes}
 
-Themes are loaded in the exact same way as plugins—the line between them is blurry. From the consumer perspective, the `themes` and `plugins` entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for [a theme to override a plugin's default theme components](./advanced/swizzling.md#theme-aliases).
+Themes are loaded in the exact same way as plugins—the line between them is blurry. From the consumer perspective, the `themes` and `plugins` entries are interchangeable when installing and configuring a plugin. The only nuance is that themes are loaded after plugins, and it's possible for [a theme to override a plugin's default theme components](./swizzling.md#theme-aliases).
 
 :::tip
 
@@ -278,7 +278,7 @@ module.exports = {
 };
 ```
 
-## Module shorthands
+## Module shorthands {#module-shorthands}
 
 Docusaurus supports shorthands for plugins, themes, and presets. When it sees a plugin / theme / preset name, it tries to load one of the following, in that order:
 
diff --git a/website/versioned_sidebars/version-2.0.0-beta.15-sidebars.json b/website/versioned_sidebars/version-2.0.0-beta.17-sidebars.json
similarity index 98%
rename from website/versioned_sidebars/version-2.0.0-beta.15-sidebars.json
rename to website/versioned_sidebars/version-2.0.0-beta.17-sidebars.json
index 3809de5a0edb..9e98f4f2209f 100644
--- a/website/versioned_sidebars/version-2.0.0-beta.15-sidebars.json
+++ b/website/versioned_sidebars/version-2.0.0-beta.17-sidebars.json
@@ -78,6 +78,7 @@
           ]
         },
         "styling-layout",
+        "swizzling",
         "static-assets",
         "search",
         "browser-support",
@@ -123,8 +124,8 @@
         "advanced/architecture",
         "advanced/plugins",
         "advanced/routing",
-        "advanced/swizzling",
-        "advanced/ssg"
+        "advanced/ssg",
+        "advanced/client"
       ]
     },
     {
diff --git a/website/versions.json b/website/versions.json
index cf622e183edd..c93a85922de0 100644
--- a/website/versions.json
+++ b/website/versions.json
@@ -1,4 +1,4 @@
 [
-  "2.0.0-beta.16",
-  "2.0.0-beta.15"
+  "2.0.0-beta.17",
+  "2.0.0-beta.16"
 ]
diff --git a/website/versionsArchived.json b/website/versionsArchived.json
index 4302438c5bb5..561012c93e6b 100644
--- a/website/versionsArchived.json
+++ b/website/versionsArchived.json
@@ -1,4 +1,5 @@
 {
+  "2.0.0-beta.15": "https://6220d0362c028b000827f851--docusaurus-2.netlify.app/docs/2.0.0-beta.15",
   "2.0.0-beta.14": "https://6218ceed1b19a70008d9c348--docusaurus-2.netlify.app/docs/2.0.0-beta.14",
   "2.0.0-beta.13": "https://61f16eafc42e860008d41557--docusaurus-2.netlify.app/docs/2.0.0-beta.13",
   "2.0.0-beta.10": "https://61c1eade2ffed20008aaac30--docusaurus-2.netlify.app/docs/2.0.0-beta.10",