Migration depuis Docusaurus

Docusaurus est un constructeur de site web de documentation populaire construit sur React.

Principales similitudes entre Docusaurus et Astro

Docusaurus et Astro partagent certaines similitudes qui vous aideront à migrer votre projet :

Astro et Docusaurus sont tous deux des créateurs de sites modernes, basés sur JavaScript (Jamstack) et destinés aux sites web axés sur le contenu, comme les sites de documentation.
Astro et Docusaurus supportent tous deux les pages MDX. Vous devriez pouvoir utiliser vos fichiers .mdx existants pour Astro.
Astro et Docusaurus utilisent le routage basé sur les fichiers pour générer automatiquement des routes de pages pour tout fichier MDX situé dans src/pages. L’utilisation de la structure de fichiers d’Astro pour votre contenu existant et lors de l’ajout de nouvelles pages devrait vous sembler familière.
Astro dispose d’une intégration officielle pour l’utilisation des composants React. Notez que dans Astro, les fichiers React doivent avoir une extension .jsx ou .tsx.
Astro supporte l’installation de paquets NPM, dont plusieurs pour React. Vous pouvez conserver tout ou partie de vos composants et dépendances React existants.
La syntaxe JSX d’Astro devrait vous sembler familière si vous avez l’habitude d’écrire React.

Principales différences entre Docusaurus et Astro

Lorsque vous reconstruisez votre site Docusaurus avec Astro, vous remarquerez quelques différences importantes :

Docusaurus est une application monopage (SPA) basée sur React. Les sites Astro sont des applications multi-pages construites en utilisant des composants .astro, mais peuvent aussi supporter React, Preact, Vue.js, Svelte, SolidJS, AlpineJS et le templating HTML brut.
Docusaurus a été conçu pour construire des sites web de documentation et possède des fonctionnalités intégrées spécifiques aux sites web de documentation que vous devriez construire vous-même dans Astro. Au lieu de cela, Astro propose certaines de ces fonctionnalités via Starlight : un thème officiel pour la documentation. Ce site web a inspiré Starlight et fonctionne désormais avec lui ! Vous pouvez également trouver d’autres thèmes de documentation communautaires avec des fonctionnalités intégrées dans notre vitrine de thèmes.
Les sites Docusaurus utilisent des pages MDX pour le contenu. Le thème docs d’Astro utilise par défaut des fichiers Markdown (.md) et ne nécessite pas l’utilisation de MDX. Vous pouvez optionnellement installer l’intégration MDX d’Astro (inclus par défaut dans notre thème Starlight) et utiliser des fichiers .mdx en plus des fichiers Markdown standards.

Passer de Docusaurus à Astro

Pour convertir un site de documentation Docusaurus en Astro, commencez par notre modèle de démarrage officiel Starlight, ou explorez d’autres thèmes de documentation communautaires dans notre vitrine de thèmes.

Vous pouvez passer un argument --template à la commande create astro pour démarrer un nouveau projet Astro avec l’un de nos modèles officiels. Vous pouvez aussi démarrer un nouveau projet à partir de n’importe quel dépôt Astro existant sur GitHub.

npm create astro@latest -- --template starlight

pnpm create astro@latest --template starlight

yarn create astro --template starlight

L’intégration MDX d’Astro est incluse par défaut, ce qui vous permet de transférer vos fichiers de contenu existants vers Starlight immédiatement.

Vous pouvez trouver la documentation d’Astro, et d’autres modèles officiels, sur astro.new. Vous trouverez un lien vers le dépôt GitHub de chaque projet, ainsi que des liens en un clic pour ouvrir un projet fonctionnel dans les environnements de développement en ligne IDX, StackBlitz, CodeSandbox et Gitpod.