Aller au contenu

Migration depuis GitBook

GitBook est une plateforme web pour la création et la publication de documentation et de livres de manière collaborative, avec une intégration du contrôle de version et des fonctionnalités personnalisables.

Principales similitudes entre GitBook et Astro

Titre de la section Principales similitudes entre GitBook et Astro

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

  • Astro et GitBook supportent tous deux Markdown. Vous pouvez migrer toute votre documentation existante en utilisant la fonctionnalité Git Sync de GitBook.

  • Astro et GitBook utilisent tous deux une forme de routage basé sur les fichiers. 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.

Principales différences entre GitBook et Astro

Titre de la section Principales différences entre GitBook et Astro

Lorsque vous migrez vos documents GitBook vers Astro, vous remarquerez quelques différences importantes :

  • Un site GitBook est édité à l’aide d’un tableau de bord en ligne. Dans Astro, vous utiliserez un éditeur de code et un environnement de développement pour maintenir votre site. Vous pouvez développer localement sur votre machine, ou choisir un éditeur/environnement de développement en nuage comme StackBlitz, CodeSandbox, ou Gitpod.

  • GitBook stocke votre contenu dans une base de données. Dans Astro, vous aurez des fichiers individuels (typiquement Markdown ou MDX) dans votre répertoire de projet pour le contenu de chaque page. Vous pouvez également choisir d’utiliser un CMS pour votre contenu et utiliser Astro pour récupérer et présenter les données.

  • GitBook utilise une syntaxe personnalisée en plus de Markdown pour le contenu. Astro prend en charge Markdoc via l’intégration optionnelle Markdoc, qui présente une syntaxe similaire à celle que vous utiliseriez dans GitBook.

Passer de GitBook à Astro

Titre de la section Passer de GitBook à Astro

Pour convertir un site de documentation GitBook en Astro, commencez par notre modèle officiel de départ pour de la documentation : 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. Ou vous pouvez démarrer un nouveau projet à partir de n’importe quel dépôt Astro existant sur GitHub.

Fenêtre de terminal
npm create astro@latest -- --template starlight

Une fois que vous avez un nouveau projet Astro, vous pouvez synchroniser votre contenu GitBook existant avec votre nouveau projet Astro. GitBook dispose d’une fonctionnalité Git Sync qui synchronisera automatiquement votre contenu GitBook avec un dépôt GitHub/GitLab.

Pour synchroniser directement la collection de contenu du modèle docs, spécifiez src/content/docs/fr ou src/content/docs comme répertoire du projet.

Après avoir synchronisé le contenu, vous aurez maintenant une copie de votre contenu GitBook dans votre dépôt Astro. Désactivez git sync pour empêcher toute synchronisation future avec GitBook.

Notez que bien que vous ayez maintenant votre contenu migré dans votre projet Astro, il ne sera pas immédiatement utilisable. Pour utiliser ce contenu dans votre site Astro, vous devrez passer un peu de temps à modifier manuellement la syntaxe de GitBook dans un format compatible avec Astro. En particulier :

  • L’intégration Markdoc d’Astro exige que l’extension du fichier soit .mdoc. Ceci afin d’éviter les conflits avec d’autres extensions Markdown comme .mdx et .md.
  • La syntaxe de GitBook diffère de celle de Markdoc où le préfixe / indiquant une balise de fermeture est remplacé par end pour les fichiers GitBook. Vous devrez mettre à jour cette notation dans vos fichiers.
  • Certaines fonctionnalités de GitBook reposent sur des composants personnalisés. Ces composants n’existent pas dans Astro et doivent être créés et ajoutés à votre projet via l’attribut tags de la configuration de Markdoc ou supprimés de vos fichiers.

Ressources de la communauté

Titre de la section Ressources de la communauté
  • Ajoutez le vôtre !

Plus de guides sur les migrations