Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(v2): add documentation for migration command #3026

Merged
merged 13 commits into from
Jul 24, 2020
Merged
Original file line number Diff line number Diff line change
@@ -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';
Expand Down Expand Up @@ -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`
Expand Down Expand Up @@ -638,6 +645,71 @@ 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
slorber marked this conversation as resolved.
Show resolved Hide resolved

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.

:::

slorber marked this conversation as resolved.
Show resolved Hide resolved
## 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.
Expand Down
2 changes: 1 addition & 1 deletion website/docs/markdown-features.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion website/sidebars.js
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ module.exports = {
'blog',
'search',
'deployment',
'migrating-from-v1-to-v2',
'guides/migrating-from-v1-to-v2',
],
},
{
Expand Down