mirror of
https://github.com/facebook/docusaurus.git
synced 2025-08-03 00:39:45 +02:00
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
Endi
parent
9b4715a70d
commit
2254e08785
1 changed files with 54 additions and 42 deletions
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue