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.
DiffĂ©rences principalesâ
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 de 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 de 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
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 s'occupera de nombreux aspects de la migration pour vous.
Cependant, certaines parties ne peuvent pas ĂȘtre facilement automatisĂ©es, et vous devrez revenir au processus manuel.
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 manuelleâ
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 demander dans le canal Discord #migration-v1-to-v2
.
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.