docs(v2): add documentation for migration command

website/docs/migrating-from-v1-to-v2.md → website/docs/guides/migrating-from-v1-to-v2.md

@@ -1,6 +1,7 @@
 ---
 id: migrating-from-v1-to-v2
 title: Migrating from v1 to v2
+slug: /migrating-from-v1-to-v2
 ---
 
 import ColorGenerator from '@site/src/components/ColorGenerator';
@@ -44,6 +45,12 @@ website
 ├── docusaurus.config.js
 ```
 
+:::tip
+
+You can use the [migration command](#migration-command) to take care of some of the migration chores.
+
+:::
+
 ## Project setup
 
 ### `package.json`
@@ -638,6 +645,72 @@ cd website
 yarn start
 ```
 
+## Migration command
+
+The migration command automatically migrates your v1 website to a v2 website.
+
+The migration command migrates:
+
+- Site configurations (from `siteConfig.js` to `docusaurus.config.js`)
+- `package.json`
+- `sidebars.json`
+- `/docs`
+- `/blog`
+- `/static`
+- `versioned_sidebar.json` and `/versioned_docs` if your site uses versioning
+
+:::info
+
+Manual tweaking is still required after using the migration command. You still need to migrate your [footer](#footer), [pages](#pages) and [content](#content).
+
+:::
+
+To use the migration command, follow these steps:
+
+1. Before using the migration command, ensure that `/docs`, `/blog`, `/static`, `sidebars.json`, `siteConfig.js`, `package.json` follow the [structure](#) shown at the start of this page.
+
+2. To migrate your v1 website, run the migration command with the appropriate filesystem paths:
+
+```
+// migration command format
+npx docusaurus-migrate migrate <v1 website directory> <desired v2 website directory>
+
+// example
+npx docusaurus-migrate migrate ./v1-website ./v2-website
+```
+
+3. To view your new website locally, go into your v2 website's directory and start your development server.
+
+```bash
+cd ./v2-website
+yarn install
+yarn start
+```
+
+#### Options
+
+You can add option flags to the migration command to automatically migrate markdown content and pages to v2. It is likely that you will still need to make some manual changes to achieve your desired result.
+
+| Name     | Description                                            |
+| -------- | ------------------------------------------------------ |
+| `--mdx`  | Add this flag to convert markdown to mdx automatically |
+| `--page` | Add this flag to migrate pages automatically           |
+
+```
+// example using options
+npx docusaurus-migrate migrate --mdx --page ./v1-website ./v2-website
+```
+
+:::danger
+
+The migration of pages and MDX is still a work in progress. 
+
+We recommend you to try to run the pages without these options, commit, and then try to run the migration again with the --page and --mdx options. 
+
+This way, you'd be able to easily inspect and fix the diff.
+
+:::
+
 ## Example migration PRs
 
 You might want to refer to our migration PRs for [Create React App](https://github.com/facebook/create-react-app/pull/7785) and [Flux](https://github.com/facebook/flux/pull/471) as examples of how a migration for a basic Docusaurus v1 site can be done.

website/docs/markdown-features.mdx

@@ -144,7 +144,7 @@ Docusaurus has built-in support for [MDX](https://mdxjs.com/), which allows you
 
 **Note 1:** While both `.md` and `.mdx` files are parsed using MDX, some of the syntax are treated slightly differently. For the most accurate parsing and better editor support, we recommend using the `.mdx` extension for files containing MDX syntax. Let's rename the previous file to `greeting.mdx`.
 
-**Note 2:** Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](migrating-from-v1-to-v2.md#convert-style-attributes-to-style-objects-in-mdx).
+**Note 2:** Since all doc files are parsed using MDX, any HTML is treated as JSX. Therefore, if you need to inline-style a component, follow JSX flavor and provide style objects. This behavior is different from Docusaurus 1. See also [Migrating from v1 to v2](guides/migrating-from-v1-to-v2.md#convert-style-attributes-to-style-objects-in-mdx).
 
 Try this block here:
 

website/sidebars.js

@@ -31,7 +31,7 @@ module.exports = {
         'blog',
         'search',
         'deployment',
-        'migrating-from-v1-to-v2',
+        'guides/migrating-from-v1-to-v2',
       ],
     },
     {