chore(v2): fix 2.0.0-alpha.50 docs

website/versioned_docs/version-2.0.0-alpha.50/configuration.md

@@ -144,52 +144,3 @@ const Hello = () => {
 If you just want to use those fields on the client side, you could create your own JS files and import them as ES6 modules, there is no need to put them in `docusaurus.config.js`.
 
 :::
-
-## Docs-only mode
-
-While Docusaurus is a performant static site generator with support for blogs, product landing and marketing pages, some sites just want the documentation component.
-
-Here are some steps you need to follow for a "docs-only mode":
-
-1. Set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site:
-
-```js {8} title="docusaurus.config.js"
-module.exports = {
-  // ...
-  presets: [
-    [
-      '@docusaurus/preset-classic',
-      {
-        docs: {
-          routeBasePath: '', // Set to empty string.
-          ...
-        },
-      },
-    ],
-  ],
-  // ...
-};
-```
-
-2. Set up a redirect to the initial document on the home page in `src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs.
-
-```jsx
-import React from 'react';
-
-import {Redirect} from '@docusaurus/router';
-import useBaseUrl from '@docusaurus/useBaseUrl';
-
-function Home() {
-  return <Redirect to={useBaseUrl('/getting-started')} />;
-}
-
-export default Home;
-```
-
-Now, when visiting your site, it will show your initial document instead of a landing page.
-
-:::tip
-
-There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode).
-
-:::

website/versioned_docs/version-2.0.0-alpha.50/creating-pages.md

@@ -5,6 +5,8 @@ title: Creating Pages
 
 In this section, we will learn about creating ad-hoc pages in Docusaurus using React. This is most useful for creating one-off standalone pages like a showcase page, playground page or support page.
 
+The functionality of pages is powered by `@docusaurus/plugin-content-pages`.
+
 ## Adding a new page
 
 <!-- TODO: What will the user see if pages/ is empty? -->
@@ -75,6 +77,12 @@ my-website
 .
 ```
 
+:::caution
+
+All JavaScript/TypeScript files within the `src/pages/` directory will have corresponding website paths generated for them. Do not put reusable components or test files (ending with `.test.js`) into that directory otherwise they will be turned into pages, which might not be intended.
+
+:::
+
 ## Using React
 
 React is used as the UI library to create pages. Every page component should export a React component and you can leverage on the expressiveness of React to build rich and interactive content.

website/versioned_docs/version-2.0.0-alpha.50/deployment.md

@@ -13,31 +13,9 @@ Once it finishes, you should see the production build under the `build/` directo
 
 You can deploy your site to static site hosting services such as [ZEIT Now](https://zeit.co/now), [GitHub Pages](https://pages.github.com/), [Netlify](https://www.netlify.com/), [Render](https://render.com/static-sites), and [Surge](https://surge.sh/help/getting-started-with-surge). Docusaurus sites are statically rendered so they work without JavaScript too!
 
-## Deploying to ZEIT Now
-
-Deploying your Docusaurus project to [ZEIT Now](https://zeit.co/now) will provide you with [various benefits](https://zeit.co/now) in the areas of performance and ease of use.
-
-Most importantly, however, deploying a Docusaurus project only takes a couple seconds:
-
-1. First, install their [command-line interface](https://zeit.co/download):
-
-```bash
-npm i -g now
-```
-
-2. Run a single command inside the root directory of your project:
-
-```bash
-now
-```
-
-**That's all.** Your docs will automatically be deployed.
-
-Now you can connect your site to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
-
 ## Deploying to GitHub Pages
 
-Docusaurus provides a easy way to publish to GitHub Pages.
+Docusaurus provides a easy way to publish to [GitHub Pages](https://pages.github.com/). Which is hosting that comes for free with every GitHub repository.
 
 ### `docusaurus.config.js` settings
 
@@ -105,13 +83,33 @@ GIT_USER=<GITHUB_USERNAME> yarn deploy
 cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
 ```
 
-<!--
+### Triggering deployment with Travis CI
-TODO: Talk about deployment steps and different hosting options.
 
-References:
+Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider.
-- https://www.gatsbyjs.org/docs/deploying-and-hosting/
 
--->
+1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/).
+1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
+1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository.
+1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
+1. Create a `.travis.yml` on the root of your repository with the following:
+
+```yaml title=".travis.yml"
+language: node_js
+node_js:
+  - '10'
+branches:
+  only:
+    - master
+cache:
+  yarn: true
+script:
+  - git config --global user.name "${GH_NAME}"
+  - git config --global user.email "${GH_EMAIL}"
+  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
+  - yarn && GIT_USER="${GH_NAME}" yarn deploy
+```
+
+Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
 
 ## Deploying to Netlify
 
@@ -142,6 +140,28 @@ Make sure to disable Netlify setting `Pretty URLs` to prevent lowercased URLs, u
 
 :::
 
+## Deploying to ZEIT Now
+
+Deploying your Docusaurus project to [ZEIT Now](https://zeit.co/now) will provide you with [various benefits](https://zeit.co/now) in the areas of performance and ease of use.
+
+Most importantly, however, deploying a Docusaurus project only takes a couple seconds:
+
+1. First, install their [command-line interface](https://zeit.co/download):
+
+```bash
+npm i -g now
+```
+
+2. Run a single command inside the root directory of your project:
+
+```bash
+now
+```
+
+**That's all.** Your docs will automatically be deployed.
+
+Now you can connect your site to [GitHub](https://zeit.co/github) or [GitLab](https://zeit.co/gitlab) to automatically receive a new deployment every time you push a commit.
+
 ## Deploying to Render
 
 Render offers [free static site hosting](https://render.com/docs/static-sites) with fully managed SSL, custom domains, a global CDN and continuous auto deploys from your Git repo. Deploy your app in just a few minutes by following these steps.
@@ -160,35 +180,7 @@ Render offers [free static site hosting](https://render.com/docs/static-sites) w
 
 That's it! Your app will be live on your Render URL as soon as the build finishes.
 
-### Deploying to Travis CI
+## Deploying to Surge
-
-Continuous integration (CI) services are typically used to perform routine tasks whenever new commits are checked in to source control. These tasks can be any combination of running unit tests and integration tests, automating builds, publishing packages to NPM, and deploying changes to your website. All you need to do to automate deployment of your website is to invoke the `yarn deploy` script whenever your website is updated. The following section covers how to do just that using [Travis CI](https://travis-ci.com/), a popular continuous integration service provider.
-
-1. Go to https://github.com/settings/tokens and generate a new [personal access token](https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/)
-1. Using your GitHub account, [add the Travis CI app](https://github.com/marketplace/travis-ci) to the repository you want to activate.
-1. Open your Travis CI dashboard. The URL looks like https://travis-ci.com/USERNAME/REPO, and navigate to the `More options` > `Setting` > `Environment Variables` section of your repository.
-1. Create a new environment variable named `GH_TOKEN` with your newly generated token as its value, then `GH_EMAIL` (your email address) and `GH_NAME` (your GitHub username).
-1. Create a `.travis.yml` on the root of your repository with the following:
-
-```yaml title=".travis.yml"
-language: node_js
-node_js:
-  - '10'
-branches:
-  only:
-    - master
-cache:
-  yarn: true
-script:
-  - git config --global user.name "${GH_NAME}"
-  - git config --global user.email "${GH_EMAIL}"
-  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
-  - yarn && GIT_USER="${GH_NAME}" yarn deploy
-```
-
-Now, whenever a new commit lands in `master`, Travis CI will run your suite of tests and if everything passes, your website will be deployed via the `yarn deploy` script.
-
-## Deploying with Surge
 
 Surge is a [static web hosting platform](https://surge.sh/help/getting-started-with-surge), it is used to deploy your Docusaurus project from command line in a minute. Deploying your project to Surge is easy and it is also free (including a custom domain and SSL).
 

website/versioned_docs/version-2.0.0-alpha.50/docs.md

@@ -1,8 +1,36 @@
 ---
-id: sidebar
+id: docs
-title: Sidebar
+title: Docs Introduction
+sidebar_label: Introduction
 ---
 
+The docs feature provides users with a way to organize Markdown files in a hierarchical format.
+
+## Document ID
+
+Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
+
+For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
+
+```bash
+website # root directory of your site
+└── docs
+   ├── greeting.md
+   └── guide
+      └── hello.md
+```
+
+However, the last part of the `id` can be defined by user in the front matter. For example, if `guide/hello.md`'s content is defined as below, its final `id` is `guide/part1`.
+
+```yml
+---
+id: part1
+---
+Lorem ipsum
+```
+
+## Sidebar
+
 To generate a sidebar to your Docusaurus site, you need to define a file that exports a sidebar object and pass that into the `@docusaurus/plugin-docs` plugin directly or via `@docusaurus/preset-classic`.
 
 ```js {8-9} title="docusaurus.config.js"
@@ -23,7 +51,7 @@ module.exports = {
 };
 ```
 
-## Sidebar object
+### Sidebar object
 
 A sidebar object is defined like this.
 
@@ -83,30 +111,7 @@ module.exports = {
 };
 ```
 
-## Document ID
+#### Sidebar item
-
-Every document has a unique `id`. By default, a document `id` is the name of the document (without the extension) relative to the root docs directory.
-
-For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`.
-
-```bash
-website # root directory of your site
-└── docs
-   ├── greeting.md
-   └── guide
-      └── hello.md
-```
-
-However, the last part of the `id` can be defined by user in the frontmatter. For example, if `guide/hello.md` content is defined as below, it's final `id` is `guide/part1`.
-
-```yml
----
-id: part1
----
-Lorem ipsum
-```
-
-## Sidebar item
 
 As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a few types we support:
 
@@ -115,7 +120,7 @@ As the name implies, `SidebarItem` is an item defined in a Sidebar. There are a
 - [Ref](#ref)
 - [Category](#category)
 
-### Doc
+#### Doc
 
 ```typescript
 type SidebarItemDoc =
@@ -155,7 +160,7 @@ module.exports = {
 };
 ```
 
-### Link
+#### Link
 
 ```typescript
 type SidebarItemLink = {
@@ -175,7 +180,7 @@ Sidebar item type that links to a non-document page. Example:
 }
 ```
 
-### Ref
+#### Ref
 
 ```typescript
 type SidebarItemRef = {
@@ -193,7 +198,7 @@ Sidebar item type that links to doc without bounding it to the sidebar. Example:
 }
 ```
 
-### Category
+#### Category
 
 This is used to add hierarchies to the sidebar:
 
@@ -237,7 +242,7 @@ module.exports = {
 };
 ```
 
-### Collapsible categories
+#### Collapsible categories
 
 For sites with a sizable amount of content, we support the option to expand/collapse a category to toggle the display of its contents. Categories are collapsible by default. If you want them to be always expanded, set `themeConfig.sidebarCollapsible` to `false`:
 
@@ -250,3 +255,50 @@ module.exports = {
   },
 }
 ```
+
+## Docs-only mode
+
+If you just want the documentation feature, you can follow the instructions for a "docs-only mode":
+
+1. Set the `routeBasePath` property of the `docs` object in `@docusaurus/preset-classic` in `docusaurus.config.js` to the root of your site:
+
+```js {8} title="docusaurus.config.js"
+module.exports = {
+  // ...
+  presets: [
+    [
+      '@docusaurus/preset-classic',
+      {
+        docs: {
+          routeBasePath: '', // Set to empty string.
+          ...
+        },
+      },
+    ],
+  ],
+  // ...
+};
+```
+
+2. Set up a redirect to the initial document on the home page in `src/pages/index.js`, e.g. for the document `getting-started`. This is needed because by default there's no page created for the root of the docs.
+
+```jsx title="src/pages/index.js"
+import React from 'react';
+
+import {Redirect} from '@docusaurus/router';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+function Home() {
+  return <Redirect to={useBaseUrl('/getting-started')} />;
+}
+
+export default Home;
+```
+
+Now, when visiting your site, it will show your initial document instead of a landing page.
+
+:::tip
+
+There's also a "blog-only mode", for those who only want to use the blog component of Docusaurus 2. You can use the same method detailed above, except that you need to delete the `src/pages/index.js` file. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode).
+
+:::

website/versioned_docs/version-2.0.0-alpha.50/installation.md

@@ -26,7 +26,7 @@ npx @docusaurus/init@next init my-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.
 
-**Important Note:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults:
+**[FB-Only]:** If you are setting up a new Docusaurus website for a Facebook open source project, use the `facebook` template instead, which comes with some useful Facebook-specific defaults:
 
 ```bash
 npx @docusaurus/init@next init my-website facebook
@@ -101,10 +101,16 @@ and contents will be generated within the `/build` directory, which can be copie
 
 There are many ways to update your Docusaurus version. One guaranteed way is to manually change the version number in `package.json` to the desired version. Note that all `@docusaurus/`-namespaced packages should be using the same version.
 
+:::important
+
+Please update to the latest Docusaurus 2 version shown at the top of the page, not what is shown below.
+
+:::
+
 ```json
   "dependencies": {
-    "@docusaurus/core": "^2.0.0-alpha.48",
+    "@docusaurus/core": "^2.0.0-alpha.49",
-    "@docusaurus/preset-classic": "^2.0.0-alpha.48",
+    "@docusaurus/preset-classic": "^2.0.0-alpha.49",
     ...
   }
 ```
@@ -126,7 +132,7 @@ You should see the correct version as output.
 Alternatively, if you are using Yarn, you can do:
 
 ```
-yarn upgrade @docusaurus/core@2.0.0-alpha.48 @docusaurus/preset-classic@2.0.0-alpha.48
+yarn upgrade @docusaurus/core@2.0.0-alpha.49 @docusaurus/preset-classic@2.0.0-alpha.49
 ```
 
 ## Problems?

website/versioned_docs/version-2.0.0-alpha.50/introduction.md

@@ -6,7 +6,7 @@ description: Docusaurus was designed from the ground up to be easily installed a
 
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
-## :warning: Disclaimer
+## Disclaimer
 
 This is an **early and alpha release** of Docusaurus 2. We are making it available early to maximize community participation and feedback. Expect it to evolve a lot over the course of the alpha-beta period. If you are adventurous enough to be an early adopter, chat with us on [**Discord**](https://discordapp.com/invite/docusaurus) :wink:.
 
@@ -18,7 +18,7 @@ This is an **early and alpha release** of Docusaurus 2. We are making it availab
 
 **Do not use this if**
 
-- :x: You need a full production-ready solution (<small>try [Docusaurus 1](https://docusaurus.io/) instead</small>)
+- :x: You need a full production-ready solution (try [Docusaurus 1](https://docusaurus.io/) instead)
 - :x: You need the translation features present in v1
 - :x: You prefer not to work with potential breaking changes and/or features not yet working properly as we improve it during alpha period
 
@@ -82,19 +82,19 @@ Many aspects of Docusaurus 2 were inspired by the best things about Gatsby and i
 
 ### GitBook
 
-Gitbook has very clean slate design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's doc site. As a result, many have to turn to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
+GitBook has very clean design and has been used by many open source projects. With its focus shifting towards a commercial product rather than an open-source tool, many of its requirements no longer fit the needs as an open source project's documentation site. As a result, many have turned to other products. You may read about Redux's switch to Docusaurus [here](https://github.com/reduxjs/redux/issues/3161).
 
-Currently, Gitbook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
+Currently, GitBook is only free for open-source and non-profit teams. Docusaurus is free for everyone.
 
 ### Jekyll
 
 Jekyll is one of the most mature static site generators around and has been a great tool to use — in fact, before Docusaurus, most of Facebook's Open Source websites are/were built on Jekyll! It is extremely simple to get started. We want to bring a similar developer experience as building a static site with Jekyll.
 
-In comparison with statically generated HTML and interactivity based on `<script />` tags, Docusaurus sites are React apps. With tooling of our current ecosystem, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
+In comparison with statically generated HTML and interactivity added using `<script />` tags, Docusaurus sites are React apps. Using modern JavaScript ecosystem tooling, we hope to set new standards on doc sites performance, asset build pipeline and optimizations, and ease to setup.
 
 ### VuePress
 
-VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you wanted a Vue-based solution, VuePress would be a decent choice.
+VuePress has many similarities with Docusaurus - both focus heavily on content-centric website and provides tailored documentation features out of the box. However, VuePress is powered by Vue, while Docusaurus is powered by React. If you want a Vue-based solution, VuePress would be a decent choice.
 
 <!-- TODO: Add a Next.js comparison -->
 

website/versioned_docs/version-2.0.0-alpha.50/markdown-features.mdx

@@ -4,12 +4,6 @@ title: Markdown Features
 description: Docusaurus uses GitHub Flavored Markdown (GFM). Find out more about Docusaurus-specific features when writing Markdown.
 ---
 
-<!--
-combining:
-- assets
-- markdown features
--->
-
 Documentation is one of your product's interfaces with your users. A well-written and well-organized set of docs helps your users understand your product quickly. Our aligned goal here is to help your users find and understand the information they need, as quickly as possible.
 
 Docusaurus 2 uses modern tooling to help you compose your interactive documentations with ease. You may embed React components, or build live coding blocks where your users may play with the code on the spot. Start sharing your eureka moments with the code your audience cannot walk away from. It is perhaps the most effective way of attracting potential users.
@@ -17,7 +11,7 @@ Docusaurus 2 uses modern tooling to help you compose your interactive documentat
 In this section, we'd like to introduce you to the tools we've picked that we believe will help you build powerful documentation. Let us walk you through with an example.
 
 :::important
-All the following content assumes you are using `@docusaurus/preset-classic`.
+All the following content assumes you are using `@docusaurus/preset-classic` or `@docusaurus/plugin-content-docs`.
 :::
 
 ---
@@ -72,6 +66,7 @@ This will render in the browser as follows:
 import BrowserWindow from '@site/src/components/BrowserWindow';
 
 <BrowserWindow url="http://localhost:3000">
+
 <h2>Hello from Docusaurus</h2>
 
 Are you ready to create the documentation site for your open source project?
@@ -94,7 +89,7 @@ The headers are well-spaced so that the hierarchy is clear.
 
 </BrowserWindow>
 
-### Markdown Headers
+## Markdown Headers
 
 Documents use the following markdown header fields that are enclosed by a line `---` on either side:
 
@@ -126,7 +121,21 @@ image: https://i.imgur.com/mErPwqL.png
 ---
 ```
 
-### Embedding React components
+
+## Referencing other documents
+
+If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
+
+For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
+
+```md
+I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md)
+[Relative document](../doc2.md) referencing works as well.
+```
+
+One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
+
+## Embedding React components with MDX
 
 Docusaurus has built-in support for [MDX](https://mdxjs.com), which allows you to write JSX within your Markdown files and render them as React components.
 
@@ -169,6 +178,7 @@ export const Highlight = ({children, color}) => (
 );
 
 <BrowserWindow minHeight={240} url="http://localhost:3000">
+
 <Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
 
 I can write **Markdown** alongside my _JSX_!
@@ -179,199 +189,6 @@ I can write **Markdown** alongside my _JSX_!
 
 You can also import your own components defined in other files or third-party components installed via npm! Check out the [MDX docs](https://mdxjs.com/) to see what other fancy stuff you can do with MDX.
 
-### Referencing other documents
-
-If you want to reference another document file, you should use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
-
-For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
-
-```md
-I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md)
-[Relative document](../doc2.md) referencing works as well.
-```
-
-One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
-
-### Syntax highlighting
-
-Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
-
-    ```jsx
-    console.log('Every repo must come with a mascot.');
-    ```
-
-<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
-
-Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
-
-```jsx
-console.log('Every repo must come with a mascot.');
-```
-
-By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js.
-
-For example, if you prefer to use the `dracula` highlighting theme:
-
-```js {3} title="docusaurus.config.js"
-module.exports = {
-  themeConfig: {
-    prism: {
-      theme: require('prism-react-renderer/themes/dracula'),
-    },
-  },
-};
-```
-
-By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
-
-To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages),
-define it in an array of additional languages.
-
-For example, if you want to add highlighting for the `powershell` language:
-
-```js {5} title="docusaurus.config.js"
-module.exports = {
-  ...
-  themeConfig: {
-    prism: {
-      additionalLanguages: ['powershell'],
-    },
-    ...
-  },
-};
-```
-
-### Line highlighting
-
-You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
-
-    ```jsx {3}
-    function HighlightSomeText(highlight) {
-      if (highlight) {
-        return 'This text is highlighted!';
-      }
-
-      return 'Nothing highlighted';
-    }
-    ```
-
-```jsx {3}
-function HighlightSomeText(highlight) {
-  if (highlight) {
-    return 'This text is highlighted!';
-  }
-
-  return 'Nothing highlighted';
-}
-```
-
-You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
-
-    ```jsx
-    function HighlightSomeText(highlight) {
-      if (highlight) {
-        // highlight-next-line
-        return 'This text is highlighted!';
-      }
-
-      return 'Nothing highlighted';
-    }
-
-    function HighlightMoreText(highlight) {
-      // highlight-start
-      if (highlight) {
-        return 'This range is highlighted!';
-      }
-      // highlight-end
-
-      return 'Nothing highlighted';
-    }
-    ```
-
-```jsx
-function HighlightSomeText(highlight) {
-  if (highlight) {
-    // highlight-next-line
-    return 'This text is highlighted!';
-  }
-  
-  return 'Nothing highlighted';
-}
-function HighlightMoreText(highlight) {
-  // highlight-start
-  if (highlight) {
-    return 'This range is highlighted!';
-  }
-  // highlight-end
-
-  return 'Nothing highlighted';
-}
-```
-
-JS style (`/* */` and `//`), JSX style (`{ /* */ }`), Python style (`# `), and HTML style (`<!-- -->`) are supported.
-
-To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
-
-```css title="/src/css/custom.css"
-.docusaurus-highlight-code-line {
-  background-color: rgb(72, 77, 91);
-  display: block;
-  margin: 0 calc(-1 * var(--ifm-pre-padding));
-  padding: 0 var(--ifm-pre-padding);
-}
-
-/* If you have a different syntax highlighting theme for dark mode. */
-html[data-theme='dark'] .docusaurus-highlight-code-line {
-  background-color: /* Color which works with dark mode syntax highlighting theme */
-}
-```
-
-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.
-
-    ```jsx {1,4-6,11}
-    import React from 'react';
-
-    function MyComponent(props) {
-      if (props.isBar) {
-        return <div>Bar</div>;
-      }
-
-      return <div>Foo</div>;
-    }
-
-    export default MyComponent;
-    ```
-
-```jsx {1,4-6,11}
-import React from 'react';
-
-function MyComponent(props) {
-  if (props.isBar) {
-    return <div>Bar</div>;
-  }
-
-  return <div>Foo</div>;
-}
-
-export default MyComponent;
-```
-
-### Code title
-
-You can add title to code block by adding `title` key after the language (leave a space between them).
-
-    ```jsx title="src/components/HelloCodeTitle.js"
-    function HelloCodeTitle(props) {
-      return <h1>Hello, {props.name}</h1>;
-    }
-    ```
-
-```jsx title="src/components/HelloCodeTitle.js"
-function HelloCodeTitle(props) {
-  return <h1>Hello, {props.name}</h1>;
-}
-```
-
 ### Configuring plugins
 
 You can expand the MDX functionalities, using plugins. An MDX plugin is usually a npm package, so you install them like other npm packages using npm. Docusaurus supports both [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins that work with MDX.
@@ -440,6 +257,405 @@ module.exports = {
 
 See more information in the [MDX documentation](https://mdxjs.com/advanced/plugins).
 
+## Tabs
+
+To show tabbed content within Markdown files, you can fall back on MDX. Docusaurus provides `<Tabs>` components out-of-the-box.
+
+```jsx
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<Tabs
+  defaultValue="apple"
+  values={[
+    { label: 'Apple', value: 'apple', },
+    { label: 'Orange', value: 'orange', },
+    { label: 'Banana', value: 'banana', },
+  ]
+}>
+<TabItem value="apple">This is an apple 🍎</TabItem>
+<TabItem value="orange">This is an orange 🍊</TabItem>
+<TabItem value="banana">This is a banana 🍌</TabItem>
+</Tabs>
+```
+
+will result in
+
+<Tabs
+  defaultValue="apple"
+  values={[
+    { label: 'Apple', value: 'apple', },
+    { label: 'Orange', value: 'orange', },
+    { label: 'Banana', value: 'banana', },
+  ]
+}>
+<TabItem value="apple">This is an apple 🍎</TabItem>
+<TabItem value="orange">This is an orange 🍊</TabItem>
+<TabItem value="banana">This is a banana 🍌</TabItem>
+</Tabs>
+
+### Syncing tab choices
+
+You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId` prop. Note that doing this will persist the choice in `localStorage` and  all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed. Not that `groupID` are globally-namespaced.
+
+```jsx {2,14}
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'macOS', value: 'mac', },
+  ]
+}>
+<TabItem value="win">Use Ctrl + C to copy.</TabItem>
+<TabItem value="mac">Use Command + C to copy.</TabItem>
+</Tabs>
+
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'macOS', value: 'mac', },
+  ]
+}>
+<TabItem value="win">Use Ctrl + V to paste.</TabItem>
+<TabItem value="mac">Use Command + V to paste.</TabItem>
+</Tabs>
+```
+
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'macOS', value: 'mac', },
+  ]
+}>
+<TabItem value="win">Use Ctrl + C to copy.</TabItem>
+<TabItem value="mac">Use Command + C to copy.</TabItem>
+</Tabs>
+
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'macOS', value: 'mac', },
+  ]
+}>
+<TabItem value="win">Use Ctrl + V to paste.</TabItem>
+<TabItem value="mac">Use Command + V to paste.</TabItem>
+</Tabs>
+
+---
+
+Tab choices with different `groupId`s will not interfere with each other:
+
+```jsx {2,14}
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'macOS', value: 'mac', },
+  ]
+}>
+<TabItem value="win">Windows in windows.</TabItem>
+<TabItem value="mac">macOS is macOS.</TabItem>
+</Tabs>
+
+<Tabs
+  groupId="non-mac-operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'Unix', value: 'unix', },
+  ]
+}>
+<TabItem value="win">Windows is windows.</TabItem>
+<TabItem value="unix">Unix is unix.</TabItem>
+</Tabs>
+```
+
+<Tabs
+  groupId="operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'macOS', value: 'mac', },
+  ]
+}>
+<TabItem value="win">Windows in windows.</TabItem>
+<TabItem value="mac">macOS is macOS.</TabItem>
+</Tabs>
+
+<Tabs
+  groupId="non-mac-operating-systems"
+  defaultValue="win"
+  values={[
+    { label: 'Windows', value: 'win', },
+    { label: 'Unix', value: 'unix', },
+  ]
+}>
+<TabItem value="win">Windows is windows.</TabItem>
+<TabItem value="unix">Unix is unix.</TabItem>
+</Tabs>
+
+## Callouts/admonitions
+
+In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions.
+Admonitions are wrapped by a set of 3 colons.
+
+Example:
+
+    :::note
+    The content and title *can* include markdown.
+    :::
+
+    :::tip You can specify an optional title
+    Heads up! Here's a pro-tip.
+    :::
+
+    :::info
+    Useful information.
+    :::
+
+    :::caution
+    Warning! You better pay attention!
+    :::
+
+    :::danger
+    Danger danger, mayday!
+    :::
+
+:::note
+The content and title *can* include markdown.
+:::
+
+:::tip
+Heads up! Here's a pro-tip.
+:::
+
+:::info
+Useful information.
+:::
+
+:::caution
+Warning! You better pay attention!
+:::
+
+:::danger
+Danger danger, mayday!
+:::
+
+### Specifying title
+
+You may also specify an optional title
+
+    :::note Your Title
+    The content and title *can* include markdown.
+    :::
+
+:::note Your Title
+The content and title *can* include markdown.
+:::
+
+## Code Blocks
+
+Code blocks within documentation are super-powered 💪.
+
+### Code title
+
+You can add a title to the code block by adding `title` key after the language (leave a space between them).
+
+    ```jsx title="src/components/HelloCodeTitle.js"
+    function HelloCodeTitle(props) {
+      return <h1>Hello, {props.name}</h1>;
+    }
+    ```
+
+```jsx title="src/components/HelloCodeTitle.js"
+function HelloCodeTitle(props) {
+  return <h1>Hello, {props.name}</h1>;
+}
+```
+
+### Syntax highlighting
+
+Code blocks are text blocks wrapped around by strings of 3 backticks. You may check out [this reference](https://github.com/mdx-js/specification) for specifications of MDX.
+
+    ```jsx
+    console.log('Every repo must come with a mascot.');
+    ```
+
+<!-- TODO: We need to allow users to pick syntax highlighting themes (maybe other than swizzling) -->
+
+Use the matching language meta string for your code block, and Docusaurus will pick up syntax highlighting automatically, powered by [Prism React Renderer](https://github.com/FormidableLabs/prism-react-renderer).
+
+```jsx
+console.log('Every repo must come with a mascot.');
+```
+
+By default, the Prism [syntax highlighting theme](https://github.com/FormidableLabs/prism-react-renderer#theming) we use is [Palenight](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/themes/palenight.js). You can change this to another theme by passing `theme` field in `prism` as `themeConfig` in your docusaurus.config.js.
+
+For example, if you prefer to use the `dracula` highlighting theme:
+
+```js {4} title="docusaurus.config.js"
+module.exports = {
+  themeConfig: {
+    prism: {
+      theme: require('prism-react-renderer/themes/dracula'),
+    },
+  },
+};
+```
+
+By default, Docusaurus comes with this subset of [commonly used languages](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js).
+
+To add syntax highlighting for any of the other [Prism supported languages](https://prismjs.com/#supported-languages),
+define it in an array of additional languages.
+
+For example, if you want to add highlighting for the `powershell` language:
+
+```js {5} title="docusaurus.config.js"
+module.exports = {
+  ...
+  themeConfig: {
+    prism: {
+      additionalLanguages: ['powershell'],
+    },
+    ...
+  },
+};
+```
+
+### Line highlighting
+
+You can bring emphasis to certain lines of code by specifying line ranges after the language meta string (leave a space after the language).
+
+    ```jsx {3}
+    function HighlightSomeText(highlight) {
+      if (highlight) {
+        return 'This text is highlighted!';
+      }
+
+      return 'Nothing highlighted';
+    }
+    ```
+
+```jsx {3}
+function HighlightSomeText(highlight) {
+  if (highlight) {
+    return 'This text is highlighted!';
+  }
+
+  return 'Nothing highlighted';
+}
+```
+
+To accomplish this, Docusaurus adds the `docusaurus-highlight-code-line` class to the highlighted lines. You will need to define your own styling for this CSS, possibly in your `src/css/custom.css` with a custom background color which is dependent on your selected syntax highlighting theme. The color given below works for the default highlighting theme (Palenight), so if you are using another theme, you will have to tweak the color accordingly.
+
+```css title="/src/css/custom.css"
+.docusaurus-highlight-code-line {
+  background-color: rgb(72, 77, 91);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
+/* If you have a different syntax highlighting theme for dark mode. */
+html[data-theme='dark'] .docusaurus-highlight-code-line {
+  background-color: /* Color which works with dark mode syntax highlighting theme */
+}
+```
+
+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.
+
+    ```jsx {1,4-6,11}
+    import React from 'react';
+
+    function MyComponent(props) {
+      if (props.isBar) {
+        return <div>Bar</div>;
+      }
+
+      return <div>Foo</div>;
+    }
+
+    export default MyComponent;
+    ```
+
+```jsx {1,4-6,11}
+import React from 'react';
+
+function MyComponent(props) {
+  if (props.isBar) {
+    return <div>Bar</div>;
+  }
+
+  return <div>Foo</div>;
+}
+
+export default MyComponent;
+```
+
+
+You can also use comments with `highlight-next-line`, `highlight-start`, and `highlight-end` to select which lines are highlighted.
+
+    ```jsx
+    function HighlightSomeText(highlight) {
+      if (highlight) {
+        // highlight-next-line
+        return 'This text is highlighted!';
+      }
+
+      return 'Nothing highlighted';
+    }
+
+    function HighlightMoreText(highlight) {
+      // highlight-start
+      if (highlight) {
+        return 'This range is highlighted!';
+      }
+      // highlight-end
+
+      return 'Nothing highlighted';
+    }
+    ```
+
+```jsx
+function HighlightSomeText(highlight) {
+  if (highlight) {
+    // highlight-next-line
+    return 'This text is highlighted!';
+  }
+
+  return 'Nothing highlighted';
+}
+
+function HighlightMoreText(highlight) {
+  // highlight-start
+  if (highlight) {
+    return 'This range is highlighted!';
+  }
+  // highlight-end
+
+  return 'Nothing highlighted';
+}
+```
+
+Supported commenting syntax:
+
+|Language|Syntax|
+|---|---|
+|JavaScript|`/* ... */` and `// ...`|
+|JSX|`{/* ... */}`|
+|Python|`# ...`|
+|HTML|`<!-- ... -->`|
+
+If there's a syntax that is not currently supported, we are open to adding them! Pull requests welcome.
+
 ### Interactive code editor
 
 (Powered by [React Live](https://github.com/FormidableLabs/react-live))
@@ -603,128 +819,4 @@ class HelloWorld {
 
 You may want to implement your own `<MultiLanguageCode />` abstraction if you find the above approach too verbose. We might just implement one in future for convenience.
 
-If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, read on for the [Syncing tab choices section](#syncing-tab-choices).
+If you have multiple of these multi-language code tabs, and you want to sync the selection across the tab instances, refer to the [Syncing tab choices section](#syncing-tab-choices).
-
-### Syncing tab choices
-
-You may want choices of the same kind of tabs to sync with each other. For example, you might want to provide different instructions for users on Windows vs users on macOS, and you want to changing all OS-specific instructions tabs in one click. To achieve that, you can give all related tabs the same `groupId`. Note that doing this will persist the choice in `localStorage` and  all `<Tab>` instances with the same `groupId` will update automatically when the value of one of them is changed.
-
-    import Tabs from '@theme/Tabs';
-    import TabItem from '@theme/TabItem';
-    <Tabs
-      groupId="operating-systems"
-      defaultValue="win"
-      values={[
-        { label: 'Windows', value: 'win', },
-        { label: 'macOS', value: 'mac', },
-      ]
-    }>
-    <TabItem value="win">Use Ctrl + C to copy.</TabItem>
-    <TabItem value="mac">Use Command + C to copy.</TabItem>
-    </Tabs>
-
-    <Tabs
-      groupId="operating-systems"
-      defaultValue="win"
-      values={[
-        { label: 'Windows', value: 'win', },
-        { label: 'macOS', value: 'mac', },
-      ]
-    }>
-    <TabItem value="win">Use Ctrl + V to paste.</TabItem>
-    <TabItem value="mac">Use Command + V to paste.</TabItem>
-    </Tabs>
-
-
-<Tabs
-  groupId="operating-systems"
-  defaultValue="win"
-  values={[
-    { label: 'Windows', value: 'win', },
-    { label: 'macOS', value: 'mac', },
-  ]
-}>
-<TabItem value="win">Use Ctrl + C to copy.</TabItem>
-<TabItem value="mac">Use Command + C to copy.</TabItem>
-</Tabs>
-
-<Tabs
-  groupId="operating-systems"
-  defaultValue="win"
-  values={[
-    { label: 'Windows', value: 'win', },
-    { label: 'macOS', value: 'mac', },
-  ]
-}>
-<TabItem value="win">Use Ctrl + V to paste.</TabItem>
-<TabItem value="mac">Use Command + V to paste.</TabItem>
-</Tabs>
-
-Tab choices with different `groupId`s will not interfere with each other:
-
-    import Tabs from '@theme/Tabs';
-    import TabItem from '@theme/TabItem';
-    <Tabs
-      groupId="non-mac-operating-systems"
-      defaultValue="win"
-      values={[
-        { label: 'Windows', value: 'win', },
-        { label: 'Unix', value: 'unix', },
-      ]
-    }>
-    <TabItem value="win">Windows is windows.</TabItem>
-    <TabItem value="unix">Unix is unix.</TabItem>
-    </Tabs>
-
-    <Tabs
-      groupId="non-mac-operating-systems"
-      defaultValue="win"
-      values={[
-        { label: 'Windows', value: 'win', },
-        { label: 'Unix', value: 'unix', },
-      ]
-    }>
-    <TabItem value="win">Windows is not unix.</TabItem>
-    <TabItem value="unix">Unix is not windows.</TabItem>
-    </Tabs>
-
-<Tabs
-  groupId="non-mac-operating-systems"
-  defaultValue="win"
-  values={[
-    { label: 'Windows', value: 'win', },
-    { label: 'Unix', value: 'unix', },
-  ]
-}>
-<TabItem value="win">Windows is windows.</TabItem>
-<TabItem value="unix">Unix is unix.</TabItem>
-</Tabs>
-
-<Tabs
-  groupId="non-mac-operating-systems"
-  defaultValue="win"
-  values={[
-    { label: 'Windows', value: 'win', },
-    { label: 'Unix', value: 'unix', },
-  ]
-}>
-<TabItem value="win">Windows is not unix.</TabItem>
-<TabItem value="unix">Unix is not windows.</TabItem>
-</Tabs>
-
-### Callouts/admonitions
-
-In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions.
-Admonitions are wrapped by a set of 3 colons.
-
-Example:
-
-  ```markdown
-  :::tip Title
-  The content and title *can* include markdown.
-  :::
-  ```
-
-:::tip Title
-The content and title *can* include markdown.
-:::

website/versioned_docs/version-2.0.0-alpha.50/migrating-from-v1-to-v2.md

@@ -5,9 +5,13 @@ title: Migrating from v1 to v2
 
 import ColorGenerator from '@site/src/components/ColorGenerator';
 
-This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
+:::caution
 
-**Note: This migration guide is targeted at Docusaurus users without translation and/or versioning features and assumes the following structure:**
+This migration guide is targeted at Docusaurus users without translation and/or versioning features.
+
+:::
+
+This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2. Your Docusaurus 1 site should have the following structure:
 
 ```sh
 ├── docs
@@ -326,7 +330,7 @@ Deprecated. Create a `CNAME` file in your `static` folder instead with your cust
 
 Deprecated. Pass it as an option to `@docusaurus/preset-classic` docs instead:
 
-```jsx {8-21} title="docusaurus.config.js"
+```jsx {8-20} title="docusaurus.config.js"
 module.exports = {
   // ...
   presets: [
@@ -471,9 +475,9 @@ In Docusaurus 2, the markdown syntax has been changed to [MDX](https://mdxjs.com
 
 Refer to the [multi-language support code blocks](markdown-features.mdx#multi-language-support-code-blocks) section.
 
-### Frontmatter
+### Front matter
 
-The Docusaurus frontmatter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
+The Docusaurus front matter fields for the blog have been changed from camelCase to snake_case to be consistent with the docs.
 
 The fields `authorFBID` and `authorTwitter` have been deprecated. They are only used for generating the profile image of the author which can be done via the `author_image_url` field.
 
@@ -523,9 +527,9 @@ The versioning feature is a work in progress! Although we've implemented docs ve
 
 ## Changes from v1
 
-Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for reasoning on v1's problem
+Read up https://v2.docusaurus.io/blog/2018/09/11/Towards-Docusaurus-2#versioning first for problems in v1's approach.
 
-### Migrate your `versioned_docs` frontmatter
+### Migrate your `versioned_docs` front matter
 
 Unlike v1, The markdown header for each versioned doc is no longer altered by using `version-${version}-${original_id}` as the value for the actual id field. See scenario below for better explanation.
 
@@ -629,7 +633,7 @@ Example `versioned_sidebars/version-1.0.0-sidebars.json`:
 
 ### Populate your `versioned_sidebars` and `versioned_docs`
 
-In v2, we use snapshot approach on documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
+In v2, we use snapshot approach for documentation versioning. **Every versioned docs does not depends on other version**. It is possible to have `foo.md` in `version-1.0.0` but it doesn't exist in `version-1.2.0`. This is not possible in previous version due to Docusaurus v1 fallback functionality (https://docusaurus.io/docs/en/versioning#fallback-functionality).
 
 For example, if your `versions.json` looks like this in v1
 

website/versioned_docs/version-2.0.0-alpha.50/styling-layout.md

@@ -124,7 +124,7 @@ The class names which will be processed by webpack into a globally unique class
 
 :::caution
 
-_This section is a work in progress._ [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).\_
+This section is a work in progress. [Welcoming PRs](https://github.com/facebook/docusaurus/issues/1640).
 
 :::
 

website/versioned_docs/version-2.0.0-alpha.50/versioning.md

@@ -5,15 +5,13 @@ title: Versioning
 
 You can use the version script to cut a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
 
-## :warning: Disclaimer
+:::caution
 
-:::important
+Consider well before starting to version your documentation.
-
-Consider it really well before starting to version your documentation.
 
 :::
 
-Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes in documentation between version**. If your documentation rarely changes, don't add versions to the website.
+Most of the times, you don't need versioning and it will just increase your build time and introduces complexity to your codebase. Versioning is **best suited for website with high-traffic and rapid changes to documentation between versions**. If your documentation rarely changes, don't add versioning to your documentation.
 
 To better understand how versioning works and see if it suits your needs, you can read on below.
 

website/versioned_sidebars/version-2.0.0-alpha.50-sidebars.json

@@ -58,11 +58,11 @@
           "items": [
             {
               "type": "doc",
-              "id": "version-2.0.0-alpha.50/markdown-features"
+              "id": "version-2.0.0-alpha.50/docs"
             },
             {
               "type": "doc",
-              "id": "version-2.0.0-alpha.50/sidebar"
+              "id": "version-2.0.0-alpha.50/markdown-features"
             },
             {
               "type": "doc",