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
This commit is contained in:
Wei Gao 2019-11-25 20:45:22 +08:00 committed by Endi
parent 9b4715a70d
commit 2254e08785

View file

@ -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.