mirror of
https://github.com/facebook/docusaurus.git
synced 2025-04-29 10:17:55 +02:00
105 lines
3.6 KiB
Text
105 lines
3.6 KiB
Text
---
|
|
slug: /migration
|
|
---
|
|
|
|
# Migration overview
|
|
|
|
This doc guides you through migrating an existing Docusaurus 1 site to Docusaurus 2.
|
|
|
|
We try to make this as easy as possible, and provide a migration CLI.
|
|
|
|
## Main differences {#main-differences}
|
|
|
|
Docusaurus 1 is a pure documentation site generator, using React as a server-side template engine, but not loading React on the browser.
|
|
|
|
Docusaurus 2, rebuilt from the ground up, generates a single-page-application, using the full power of React in the browser. It allows for more customizability but preserved the best parts of Docusaurus 1 - easy to get started, versioned docs, and i18n.
|
|
|
|
Beyond that, Docusaurus 2 is a **performant static site generator** and can be used to create common content-driven websites (e.g. Documentation, Blogs, Product Landing and Marketing Pages, etc) extremely quickly.
|
|
|
|
While our main focus will still be helping you get your documentations right and well, it is possible to build any kind of website using Docusaurus 2 as it is just a React application. **Docusaurus can now be used to build any website, not just documentation websites.**
|
|
|
|
## Docusaurus 1 structure {#docusaurus-1-structure}
|
|
|
|
Your Docusaurus 1 site should have the following structure:
|
|
|
|
```bash
|
|
├── docs
|
|
└── website
|
|
├── blog
|
|
├── core
|
|
│ └── Footer.js
|
|
├── package.json
|
|
├── pages
|
|
├── sidebars.json
|
|
├── siteConfig.js
|
|
└── static
|
|
```
|
|
|
|
## Docusaurus 2 structure {#docusaurus-2-structure}
|
|
|
|
After the migration, your Docusaurus 2 site could look like:
|
|
|
|
```sh
|
|
├── docs
|
|
└── website
|
|
├── blog
|
|
├── src
|
|
│ ├── components
|
|
│ ├── css
|
|
│ └── pages
|
|
├── static
|
|
├── package.json
|
|
├── sidebars.json
|
|
├── docusaurus.config.js
|
|
```
|
|
|
|
:::info
|
|
|
|
This migration does not change the `/docs` folder location, but Docusaurus v2 sites generally have the `/docs` folder inside `/website`
|
|
|
|
You are free to put the `/docs` folder anywhere you want after having migrated to v2.
|
|
|
|
:::
|
|
|
|
## Migration process {#migration-process}
|
|
|
|
There are multiple things to migrate to obtain a fully functional Docusaurus 2 website:
|
|
|
|
- packages
|
|
- CLI commands
|
|
- site configuration
|
|
- Markdown files
|
|
- sidebars file
|
|
- pages, components and CSS
|
|
- versioned docs
|
|
- i18n support 🚧
|
|
|
|
## Automated migration process {#automated-migration-process}
|
|
|
|
The [migration CLI](./migration-automated.mdx) will handle many things of the migration for you.
|
|
|
|
However, some parts can't easily be automated, and you will have to fallback to the manual process.
|
|
|
|
:::note
|
|
|
|
We recommend running the migration CLI, and complete the missing parts thanks to the manual migration process.
|
|
|
|
:::
|
|
|
|
## Manual migration process {#manual-migration-process}
|
|
|
|
Some parts of the migration can't be automated (particularly the pages), and you will have to migrate them manually.
|
|
|
|
The [manual migration guide](./migration-manual.mdx) will give you all the manual steps.
|
|
|
|
## Support {#support}
|
|
|
|
For any questions, you can ask in the [`#migration-v1-to-v2` Discord channel](https://discord.gg/C3P6CxMMxY).
|
|
|
|
Feel free to tag [@slorber](https://github.com/slorber) in any migration PRs if you would like us to have a look.
|
|
|
|
We also have volunteers willing to [help you migrate your v1 site](https://github.com/facebook/docusaurus/issues/1834).
|
|
|
|
## Example migration PRs {#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.
|