docs(v2): Reorganize migration guide (#2036)

* reorganize migration guide headings * wip about <AUTOGENERATED_TABLE_OF_CONTENTS> * add description about AUTOGENERATED_TABLE_OF_CONTENTS * Update website/docs/migrating-from-v1-to-v2.md
facebook · Nov 25, 2019 · 2254e08 · 2254e08
1 parent 9b4715a
commit 2254e08
Showing 1 changed file with 54 additions and 42 deletions.
diff --git a/website/docs/migrating-from-v1-to-v2.md b/website/docs/migrating-from-v1-to-v2.md
@@ -20,9 +20,11 @@ This doc guides you through migrating an existing Docusaurus 1 site to Docusauru
     └── static
 ```
 
-## Update `package.json`
+## Project setup
 
-### Scoped package names
+### `package.json`
+
+#### Scoped package names
 
 In Docusaurus 2, we use scoped package names:
 
@@ -43,7 +45,7 @@ Meanwhile, the default doc site functionalities provided by Docusaurus 1 are now
 }
 ```
 
-### CLI commands
+#### CLI commands
 
 Meanwhile, CLI commands are renamed to `docusaurus <command>` (instead of `docusaurus-command`).
 
@@ -89,7 +91,42 @@ A typical Docusaurus 2 `package.json` may look like this:
 }
 ```
 
-## Migrate `siteConfig` to `docusaurus.config.js`
+### Update references to the `build` directory
+
+In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`. However, in Docusaurus 2, it is now moved to just `website/build`. Make sure that you update your deployment configuration to read the generated files from the correct `build` directory.
+
+If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script.
+
+### `.gitignore`
+
+The `.gitignore` in your `website` should contain:
+
+```
+# dependencies
+/node_modules
+
+# production
+/build
+
+# generated files
+.docusaurus
+.cache-loader
+
+# misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+```
+
+## Site configurations
+
+### `docusaurus.config.js`
 
 Rename `siteConfig.js` to `docusaurus.config.js`. In Docusaurus 2, we split each functionality (blog, docs, pages) into plugins for modularity. Presets are bundles of plugins and for backward compatibility we built a `@docusaurus/preset-classic` preset which bundles most of the essential plugins present in Docusaurus 1.
 
@@ -118,6 +155,8 @@ module.exports = {
 
 Refer to migration guide below for each field in `siteConfig.js`.
 
+### Updated fields
+
 #### `baseUrl`, `tagline`, `title`, `url`, `favicon`, `organizationName`, `projectName`, `githubHost`, `scripts`, `stylesheets`
 
 No actions needed.
@@ -372,7 +411,9 @@ The following fields are all deprecated, you may remove from your configuration
 
 We intend to implement many of the deprecated config fields as plugins in future. Help will be appreciated!
 
-## Migrate your sidebar
+## Components
+
+### Sidebar
 
 In previous version, nested sidebar category is not allowed and sidebar category can only contain doc id. However, v2 allows infinite nested sidebar and we have many types of [Sidebar Item](sidebar.md#sidebar-item) other than document.
 
@@ -388,7 +429,7 @@ You'll have to migrate your sidebar if it contains category type. Rename `subcat
 },
 ```
 
-## Delete footer file
+### Footer
 
 `website/core/Footer.js` is no longer needed. If you want to modify the default footer provided by docusaurus, [swizzle](using-themes.md#swizzling-theme-components) it:
 
@@ -398,7 +439,7 @@ npm run swizzle @docusaurus/theme-classic Footer
 
 This will copy the current `<Footer />` component used by the theme to a `src/theme/Footer` directory under the root of your site, you may then edit this component for customization.
 
-## Update your page files
+### Pages
 
 Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pages work. After reading that, notice that you have to move `pages/en` files in v1 to `src/pages` instead.
 
@@ -408,7 +449,11 @@ Please refer to [creating pages](creating-pages.md) to learn how Docusaurus 2 pa
   - Index page - [Flux](https://github.com/facebook/flux/blob/master/website/src/pages/index.js) (recommended), [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/index.js), [Hermes](https://github.com/facebook/hermes/blob/master/website/src/pages/index.js),
   - Help/Support page - [Docusaurus 2](https://github.com/facebook/docusaurus/blob/master/website/src/pages/help.js), [Flux](http://facebook.github.io/flux/support)
 
-## Update your docs
+## Content
+
+### Remove AUTOGENERATED_TABLE_OF_CONTENTS
+
+This feature is deprecated. You may read more about it in [this issue](https://github.com/facebook/docusaurus/issues/1549). If you need the feature, use [remark-toc](https://github.com/remarkjs/remark-toc) instead and pass it to docs plugin's `remarkPlugins` option.
 
 ### Update Markdown syntax to be MDX-compatible
 
@@ -418,39 +463,12 @@ 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.
 
-## Update blog
+### Frontmatter
 
 The Docusaurus frontmatter 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.
 
-## Update `.gitignore`
-
-The `.gitignore` in your `website` should contain:
-
-```
-# dependencies
-/node_modules
-
-# production
-/build
-
-# generated files
-.docusaurus
-.cache-loader
-
-# misc
-.DS_Store
-.env.local
-.env.development.local
-.env.test.local
-.env.production.local
-
-npm-debug.log*
-yarn-debug.log*
-yarn-error.log*
-```
-
 ## Test your site
 
 After migration, your folder structure should look like this:
@@ -479,12 +497,6 @@ cd website
 yarn start
 ```
 
-## Update references to the `build` directory
-
-In Docusaurus 1, all the build artifacts are located within `website/build/<PROJECT_NAME>`. However, in Docusaurus 2, it is now moved to just `website/build`. Make sure that you update your deployment configuration to read the generated files from the correct `build` directory.
-
-If you are deploying to GitHub pages, make sure to run `yarn deploy` instead of `yarn publish-gh-pages` script.
-
 ## 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.