Skip to main content
Exportez le contenu GitBook vers un référentiel Git avec Git Sync pour la migration la plus complète, ou scrapez un site GitBook public pour créer un projet Mintlify initial.

​
Choisir une méthode

Utilisez Git Sync pour la migration principale lorsque cela est possible. Un site GitBook est composé de sections, et une section peut avoir plusieurs variantes, tandis que Git Sync fonctionne au niveau de la section. Exportez chaque section qui apparaît sur le site publié.
GitBook appelle désormais les conteneurs de contenu à l’intérieur d’un site des sections. La documentation GitBook plus ancienne et les scripts communautaires les appellent des espaces.

​
Exporter une section avec Git Sync

GitBook ne fournit pas de téléchargements directs au format Markdown pour les pages individuelles. Pour exporter une section au format Markdown :
  1. Créez un référentiel GitHub ou GitLab vide ou une branche vide dans un référentiel de migration.
  2. Dans la section que vous souhaitez exporter, cliquez sur Set up à côté de Git Sync dans l’en-tête de la section.
  3. Dans la liste des fournisseurs, cliquez sur GitHub Sync ou GitLab Sync, puis authentifiez-vous si vous n’avez pas encore connecté le fournisseur.
  4. Sélectionnez le référentiel vide et la branche pour l’export.
  5. Pour la direction de synchronisation initiale, choisissez GitBook → GitHub ou GitBook → GitLab.
  6. Démarrez la synchronisation initiale. Une fois terminée, clonez ou téléchargez le référentiel.
  7. Répétez pour chaque section, langue ou version que vous devez migrer.
La direction de synchronisation initiale est importante. Choisir GitHub → GitBook ou GitLab → GitBook remplace le contenu de votre section par la branche sélectionnée au lieu d’exporter la section. Vérifiez que la direction commence à GitBook et cible votre référentiel vide. Si vous choisissez la mauvaise direction, revenez à la révision précédant l’opération Git Sync dans l’historique des versions de la section.
Conservez le référentiel synchronisé inchangé comme instantané de migration. Créez une branche ou une copie pour votre conversion Mintlify.

​
Migrer un site public

Le scraper écrase les fichiers existants dans un répertoire.Exécutez le scraper dans un répertoire vide.
Le scraper charge la navigation rendue de GitBook, télécharge les images accessibles, convertit les blocs courants et crée un docs.json. Il ne peut pas récupérer les sections privées, les modifications non publiées, les autorisations, les commentaires ou l’historique des révisions. Comparez le projet généré avec votre export Git Sync lorsque les deux sont disponibles. Le scrape est utile pour vérifier la conversion des blocs rendus. L’export est le meilleur inventaire du contenu source.

​
Comprendre l’export Git Sync

GitBook crée ou utilise normalement les fichiers et répertoires suivants :
  • README.md : Page d’accueil de la section
  • SUMMARY.md : Table des matières
  • .gitbook.yaml : Racine du contenu, structure et redirections de section
  • .gitbook/assets/ : Images et fichiers téléversés
  • .gitbook/includes/ : Contenu réutilisable
Les chemins peuvent différer lorsque la configuration GitBook définit une autre racine de contenu, une autre page d’accueil ou un autre fichier de sommaire. Confirmez votre configuration spécifique avant de déplacer des fichiers.

​
Convertir la navigation SUMMARY.md

SUMMARY.md est une liste Markdown imbriquée. Convertissez ses titres et ses liens en navigation docs.json : Supprimez les extensions .md des chemins de navigation, mais ne renommez pas chaque fichier avant de vérifier les liens. Une page telle que guides/README.md peut devenir guides/index.mdx ou rester un fichier Markdown avec un chemin de navigation différent. Chaque page Mintlify nécessite également un frontmatter contenant au moins un title. Ajoutez ou convertissez le frontmatter au fur et à mesure de la migration de chaque page.
Les scripts communautaires peuvent automatiser le mappage récursif de SUMMARY.md. Vérifiez les déplacements de fichiers générés et les commandes shell avant de les exécuter. Un convertisseur doit gérer les liens manquants, les URL externes, les pages en double, les groupes imbriqués et les racines de contenu GitBook sans écraser les fichiers sources.

​
Convertir les blocs GitBook

GitBook représente de nombreux blocs avec des directives {% ... %}. Convertissez ces directives en composants Mintlify. GitBook exporte certains blocs personnalisés au format HTML car ils n’ont pas de représentation Markdown. Passez en revue chaque bloc HTML pour vérifier qu’il fonctionne de la même manière en MDX.

​
Convertir le contenu réutilisable

GitBook exporte le contenu réutilisable dans .gitbook/includes/ et le référence avec des directives d’include. Convertissez chaque fichier réutilisable en un snippet Mintlify, puis remplacez l’include GitBook par un import MDX et un composant. Par exemple :
Vérifiez le contenu réutilisable partagé entre plusieurs sections. GitBook attribue une section parente qui possède le contenu et qui est le seul endroit où il peut être modifié, de sorte que des exports de section distincts peuvent contenir des références dupliquées ou inter-sections qui doivent devenir un seul snippet partagé.

​
Migrer les sections, les variantes et les traductions

Un site GitBook publie une ou plusieurs sections, organise les sections liées en groupes et utilise des variantes pour les versions ou les langues. Choisissez le modèle de navigation Mintlify le plus proche :
  • Mappez les sections de produit ou d’audience à des produits, des onglets ou des ancrages.
  • Mappez les variantes de version à des versions.
  • Mappez les sections traduites à des langues.
  • Mappez les collections de contenu indépendantes à des groupes distincts lorsque les utilisateurs n’ont pas besoin d’un sélecteur.
Notez la variante par défaut et chaque slug de variante avant de changer de domaine. GitBook peut omettre le slug de la variante par défaut de son URL publique, donc les redirections doivent tenir compte à la fois du chemin par défaut et des chemins nommés explicitement. Copiez .gitbook/assets/ dans votre référentiel Mintlify et mettez à jour les chemins d’image et de téléchargement relatifs. Passez en revue les images inline qui utilisent le HTML pour le dimensionnement ou l’alignement. Ne laissez pas de ressources de production requises sur GitBook, sauf si vous prévoyez de conserver cet hébergement après la migration. Les redirections GitBook peuvent exister dans votre fichier de configuration et dans les paramètres au niveau du site. Rassemblez les deux sources et convertissez-les en redirections Mintlify. GitBook applique une redirection dans son fichier de configuration à une section, tandis qu’une redirection Mintlify s’applique au site publié : incluez donc l’ancien préfixe de section ou de variante si nécessaire.

​
Migrer la documentation OpenAPI

GitBook peut stocker les spécifications OpenAPI au niveau de l’organisation et placer les blocs OpenAPI générés dans les sections. L’export Markdown de section peut ne pas être la source de vérité pour ces spécifications.
  1. Inventoriez chaque spécification OpenAPI dans votre organisation GitBook.
  2. Récupérez le fichier original, l’URL source hébergée ou la spécification via l’API GitBook.
  3. Ajoutez le fichier JSON ou YAML à votre référentiel Mintlify.
  4. Configurez des pages générées par OpenAPI.
  5. Recréez les explications adjacentes à partir des blocs GitBook normaux.
  6. Comparez l’authentification, les URL de serveur, les exemples et les extensions OpenAPI spécifiques à GitBook avec vos pages API Mintlify.

​
Vérifier votre migration

Comparez chaque section exportée et chaque entrée SUMMARY.md à docs.json, puis vérifiez chaque section, groupe, variante et langue. Recherchez dans vos fichiers convertis toute syntaxe GitBook résiduelle : {%, {% end, .gitbook/includes et les blocs HTML bruts que GitBook exporte à la place du Markdown.

​
Lancez votre nouveau site

  • Instaurez un gel de contenu sur votre ancien site et suivez chaque modification qui y est apportée après votre instantané de migration.
  • Confirmez votre branche de production et votre référentiel sur la page Paramètres Git de votre tableau de bord.
  • Notez vos enregistrements DNS existants et gardez votre ancien site en ligne jusqu’à ce que vous ayez vérifié que votre déploiement Mintlify est actif.
  • Vérifiez la barre de navigation, le pied de page, le favicon, le logo, les couleurs et la typographie.
  • Vérifiez les métadonnées du site et des pages, les URL canoniques et les préférences d’indexation. Voir Paramètres SEO et de recherche.
  • Installez toutes les intégrations d’analytique requises, et ajoutez éventuellement une page 404 personnalisée.
  • Si vous avez migré une référence API, comparez les pages d’endpoints, la structure de navigation, les URL de serveur, les schémas d’authentification et les exemples avec votre ancien site.
  • Prévisualisez votre commit de lancement exact dans un déploiement de prévisualisation. Vérifiez les mises en page desktop et mobile, les pages de chaque section de navigation, la recherche et vos redirections.
  • Vérifiez la console du navigateur et l’onglet réseau pour détecter d’éventuelles erreurs sur les pages qui utilisent des composants ou des scripts personnalisés.
  • Basculez votre domaine avec le guide sur les domaines personnalisés, qui couvre la bascule sans interruption pour un domaine qui sert déjà de la documentation.
  • Après le lancement, surveillez les erreurs 404, les échecs de redirection et les échecs de build.

​
Références GitBook

Sujets connexes

Vue d'ensemble de la migrationMigrer depuis FernMigrer depuis Document360