Vue d'ensemble

Ce document vous guide à travers la migration d'un site Docusaurus 1 existant vers Docusaurus 2.

Nous essayons de rendre cela aussi facile que possible, et fournissons un CLI de migration.

Main differences

Docusaurus 1 est un pur générateur de sites de documentation, utilisant React comme moteur de template côté serveur, mais ne chargeant pas React sur le navigateur.

Docusaurus 2, reconstruit à partir de zéro et génère une application mono-page, utilisant toute la puissance de React dans le navigateur. Il permet une plus grande personnalisation tout en préservant les meilleures fonctionnalités de Docusaurus 1 : facilité la mise en route, docs versionnées et 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.

Même si notre objectif principal sera toujours de vous aider à obtenir des documentations correctes et bien faites, il est possible de construire n'importe quel type de site Web à l'aide de Docusaurus 2 puisqu'il s'agit simplement d'une application React. Docusaurus can now be used to build any website, not just documentation websites.

Docusaurus 1 structure

Votre site Docusaurus 1 devrait avoir la structure suivante :

├── docs
└── website
    ├── blog
    ├── core
    │   └── Footer.js
    ├── package.json
    ├── pages
    ├── sidebars.json
    ├── siteConfig.js
    └── static

Docusaurus 2 structure

Après la migration, votre site Docusaurus 2 pourrait ressembler à :

├── 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

Il y a plusieurs choses à migrer pour obtenir un site web Docusaurus 2 entièrement fonctionnel :

• paquets
• Commandes du CLI
• configuration du site
• Fichiers Markdown
• fichier sidebars (barres latérales)
• pages, composants et CSS
• docs versionnées
• support i18n 🚧

Automated migration process

The migration CLI will handle many things of the migration for you.

Cependant, certaines parties ne peuvent pas être facilement automatisées, et vous devrez revenir au processus manuel.

remarque

Nous vous recommandons d'exécuter le CLI, et de compléter les pièces manquantes grâce au processus de migration manuelle.

Manual migration process

Certaines parties de la migration ne peuvent pas être automatisées (en particulier les pages), et vous devrez les migrer manuellement.

The manual migration guide will give you all the manual steps.

Support

For any questions, you can ask in the #migration-v1-to-v2 Discord channel.

Feel free to tag @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.

Example migration PRs

You might want to refer to our migration PRs for Create React App and Flux as examples of how a migration for a basic Docusaurus v1 site can be done.