Migration de GitBook vers Docsbook : un guide étape par étape

Vous avez atteint le point où le tarif par utilisateur de GitBook augmente plus rapidement que la documentation. Ou le prix de l'add-on AI. Ou vous avez remarqué que vous payez une facture annuelle pour un site de documentation qui ne s'indexe pas bien. Voici le guide de migration pratique.

La plupart des équipes complètent cela en moins de trois heures. La partie coûteuse concerne les redirections.

TL;DR#

1. Exporter le contenu de GitBook au format markdown
2. Pousser vers un nouveau dépôt GitHub
3. Connecter Docsbook à ce dépôt (5 secondes)
4. Vérifier le site à docsbook.io/yourorg/yourrepo
5. Connecter votre domaine personnalisé docs.yourcompany.com à Docsbook
6. Configurer des redirections depuis les anciens chemins GitBook
7. Mettre à jour les liens internes sur votre site

Étape 1 : Exporter depuis GitBook#

GitBook prend en charge l'exportation markdown via les paramètres de l'espace de travail :

• Ouvrez votre espace GitBook
• Paramètres → Synchroniser avec Git → "Synchroniser GitBook avec le fournisseur Git"
• Choisissez GitHub, sélectionnez un nouveau dépôt privé ou public
• GitBook synchronise votre contenu en tant que markdown avec frontmatter

Alternative (sans synchronisation Git) : utilisez l'option "Exporter vers Markdown" dans le menu de l'espace et décompressez le résultat localement.

La structure de dossier que GitBook exporte :

README.md
SUMMARY.md
docs/
  introduction.md
  guides/
    quick-start.md
  api/
    auth.md

Étape 2 : Ajuster aux conventions de Docsbook#

Deux petites différences à gérer :

SUMMARY.md est optionnel dans Docsbook#

GitBook utilise SUMMARY.md comme source de navigation. Docsbook construit la navigation à partir de votre structure de dossiers et des frontmatter title automatiquement.

Vous pouvez garder SUMMARY.md (Docsbook l'ignore) ou le supprimer. La plupart des équipes le suppriment.

Matière préalable#

Matière préalable de GitBook :

---
description: How to authenticate
---

Docsbook lit le même champ description plus title optionnel. Si title est manquant, le premier H1 est utilisé.

Un script de migration simple :

find . -name "*.md" -not -path "./.git/*" -exec \
  sed -i.bak '1,/^---$/ s/^description:/description:/' {} \;

(Aucun changement nécessaire dans la plupart des cas — la matière préalable de GitBook et de Docsbook est compatible.)

Étape 3 : Connecter Docsbook#

• Allez sur docsbook.io
• Connectez-vous avec GitHub
• Collez github.com/yourorg/yourrepo
• Site en direct à docsbook.io/yourorg/yourrepo dans 5 secondes

Si votre dépôt a un dossier docs/, Docsbook l'utilise. Si vos documents se trouvent à la racine, cela fonctionne aussi.

Étape 4 : Domaine personnalisé#

Docsbook sert docs.yourcompany.com avec SSL automatique.

Dans le tableau de bord de Docsbook :

• Paramètres → Domaine
• Entrez docs.yourcompany.com
• Mettez à jour votre DNS : CNAME docs → cname.vercel-dns.com
• SSL est automatique et gratuit

Étape 5 : Les redirections#

C'est la seule étape qui compte pour le SEO. Les URL de GitBook ressemblent à :

docs.yourcompany.com/v/1.0/api/authentication

URL de Docsbook :

docs.yourcompany.com/api/authentication

Vous avez deux options :

Option A : redirection au niveau DNS/CDN#

Si vous avez Cloudflare devant votre domaine, ajoutez des règles de page :

docs.yourcompany.com/v/*/api/* → docs.yourcompany.com/api/$2 [301]

Option B : redirection via Docsbook#

Ajoutez un fichier _redirects (si votre stack le supporte) à la racine de votre dépôt :

/v/1.0/api/auth /api/auth 301
/v/1.0/api/webhooks /api/webhooks 301

Un 301 préserve l'autorité SEO. Un 302 ne le fait pas — utilisez 301.

Étape 6 : Mettre à jour les références internes#

Recherchez et remplacez dans votre code :

grep -rl "docs.yourcompany.com/v/" . | xargs sed -i.bak 's|docs.yourcompany.com/v/[0-9.]*/|docs.yourcompany.com/|g'

Mettre à jour :

• Le lien de pied de page de votre application produit
• Votre site marketing
• Vos liens README sur GitHub
• Les réponses enregistrées de votre équipe de support

Étape 7 : Vérifiez la surface AI#

Docsbook génère llms.txt, llms-full.txt, JSON-LD et sitemap automatiquement. Vérifiez :

curl https://docs.yourcompany.com/llms.txt | head -20
curl https://docs.yourcompany.com/sitemap.xml | head -10

Voir llms.txt : le guide complet pour ce à quoi s'attendre.

Qu'est-ce qui s'améliore#

Ce qui pourrait casser#

• Blocs spécifiques à GitBook — sections réductibles, blocs d'astuces, onglets. Docsbook prend en charge le markdown standard + les blocs spécifiques à Docsbook. La plupart des astuces GitBook se réécrivent proprement en > [!NOTE] appels.
• Intégration OpenAPI personnalisée — GitBook a son propre moteur de rendu de référence API. Docsbook rend OpenAPI via vos outils existants ou des liens externes.
• Historique de chat AI de GitBook — ne se transfère pas. Le chat commence frais avec votre nouveau contenu.

Temps#

Selon notre expérience d'aide aux équipes pour la migration :

• Fondateur solo, ~50 pages : 1 heure
• Petite startup, ~200 pages : 3 heures
• Entreprise en phase intermédiaire, ~1000 pages, domaine personnalisé : une demi-journée

La partie coûteuse est de communiquer le changement d'URL en interne et de mettre à jour les réponses enregistrées dans votre outil de support.

Commencer gratuitement — pas de carte de crédit

Étapes suivantes#

• GitBook vs Docsbook — la comparaison fonctionnalité par fonctionnalité derrière ce mouvement
• Domaine personnalisé pour la documentation — la partie DNS et SSL de l'étape 4
• Guide SEO de la documentation — comment maintenir les classements à travers le changement d'URL