Vue d'ensemble de la migration

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.

Les principales différences

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.

En outre, Docusaurus 2 est un générateur de sites statiques performant et peut être utilisé pour créer extrêmement rapidement des sites Web courants axés sur le contenu (par exemple, documentation, blogs, pages de présentation de produit et de marketing, etc).

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 peut maintenant être utilisé pour construire n'importe quel site web, pas seulement des sites de documentation.

Structure Docusaurus 1

Votre site Docusaurus 1 devrait avoir la structure suivante :

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

Structure Docusaurus 2

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

Cette migration ne change pas l'emplacement du dossier /docs, mais les sites Docusaurus v2 ont généralement le dossier /docs à l'intérieur de /website

Vous êtes libre de mettre le dossier /docs où vous voulez après avoir migré en v2.

Processus de migration

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 🚧

Processus de migration automatisé

Le CLI de migration se chargera pour vous de nombreuses choses de la migration.

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.

Processus de migration manuel

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

Le guide de migration manuel vous donnera toutes les étapes manuelles.

Support

Pour toute question, vous pouvez les poser dans le canal #migration-v1-to-v2 de Discord.

N'hésitez pas à mentionner @slorber dans vos PR de migration si vous souhaitez que nous y jetions un œil.

Nous avons également des bénévoles prêts à vous aider à migrer votre site v1.

Exemple de PR de migration

Vous pouvez vous référer à nos PR de migration pour Create React App et Flux de la façon dont une migration pour un site Docusaurus v1 de base peut être effectuée.