Dépannage

J'ai une erreur de synchronisation avec GitHub

Assurez-vous de créer uniquement des fichiers readme dans votre dépôt

Lorsque la synchronisation Git est activée, faites attention à ne pas créer de fichiers readme via l'interface GitBook. Créer des fichiers readme via l'interface GitBook :

• Crée des fichiers README en double dans votre dépôt

• Provoque des conflits d'affichage entre GitBook et GitHub

• Peut perturber les compilations et les processus de déploiement

• Donne lieu à une priorité de fichier imprévisible

Cela inclut les fichiers nommés README.md, readme.md, Readme.md, et README (sans extension). Au lieu de cela, souvenez-vous de gérer votre fichier README directement dans votre dépôt git.

Rencontrez-vous toujours des erreurs ?

Assurez-vous que :‌

• Votre dépôt possède un README.md fichier à sa racine (ou dans le répertoire racine dossier spécifié dans votre .gitbook.yaml) qui a été créé directement dans votre dépôt git. Ce fichier est requis et sert de page d'accueil pour votre documentation. Pour plus de détails, consultez notre configuration du contenu.

• Si vous avez des en-têtes YAML dans vos fichiers Markdown, assurez-vous qu'ils sont valides en utilisant un analyseur.​

​GitBook n'utilise pas mon docs dossier

Par défaut, GitBook utilise la racine du dépôt comme point de départ. Un répertoire spécifique peut être précisé pour définir le périmètre des fichiers markdown. Consultez notre documentation sur configuration du contenu pour plus de détails.‌

GitBook crée de nouveaux fichiers markdown

Lors de la synchronisation et de la modification depuis GitBook avec un dépôt Git existant, GitBook peut créer de nouveaux fichiers markdown au lieu d'utiliser ceux existants.‌ Cela permet de s'assurer que GitBook n'écrase pas les fichiers qui existaient auparavant dans votre dépôt.

Les redirections ne fonctionnent pas correctement

Le fichier YAML doit être correctement formaté pour que les redirections fonctionnent. Des erreurs telles qu'une indentation incorrecte ou des espaces blancs peuvent entraîner le dysfonctionnement de vos redirections. La validation de votre fichier YAML peut garantir que les redirections fonctionneront sans problème.

Lors de la configuration des redirections, n'ajoutez pas de barres obliques initiales. Par exemple, tenter de rediriger vers ./misc/support.md ne fonctionnera pas.

Il est également important de considérer que tant qu'une page existe pour un chemin donné, GitBook ne cherchera pas de redirection possible. Donc, si vous configurez une redirection d'une ancienne page vers une nouvelle, vous devrez supprimer l'ancienne page pour que la redirection fonctionne.

​Mon dépôt n'est pas répertorié

Pour les dépôts GitHub

Assurez-vous d'avoir installé l'application GitHub de GitBook aux emplacements appropriés (lors de l'installation de l'application, vous pouvez choisir de l'installer sur votre compte GitHub personnel ou sur toute organisation pour laquelle vous avez des autorisations) et d'avoir accordé à l'application les autorisations correctes pour les dépôts.

Pour les dépôts GitLab

Assurez-vous que votre jeton d'accès est configuré avec les autorisations suivantes :

• api

• read_repository

• write_repository

​Rien ne se passe sur GitBook après avoir ajouté un nouveau fichier à mon dépôt

Cette section traite spécifiquement des problèmes lorsqu'un SUMMARY.md fichier existe déjà

Si votre dépôt n'inclut pas de SUMMARY.md fichier, GitBook en créera automatiquement un lors de la première synchronisation. Cela signifie que si vous avez modifié votre contenu depuis GitBook au moins une fois après avoir configuré la synchronisation Git, GitBook aurait dû créer ce fichier automatiquement.‌

Si, après avoir mis à jour votre dépôt en ajoutant ou en modifiant un fichier markdown, vous ne voyez pas la mise à jour reflétée sur GitBook et que la barre latérale n'indique pas d'erreur lors de la synchronisation, il est probable que votre ou vos fichier(s) modifié(s) ne soient pas répertorié(s) dans votre SUMMARY.md fichier.‌

Cela peut être dû soit au fait que vous avez créé le fichier manuellement, soit parce que vous avez effectué une modification sur GitBook et que la phase d'export de GitBook vers Git de la synchronisation l'a créé pour vous.

Le contenu de ce fichier reflète votre table des matières sur GitBook et est utilisé lors de la phase d'import de Git vers GitBook de la synchronisation pour recréer votre table des matières et réconcilier les prochaines mises à jour du dépôt avec votre contenu existant sur GitBook.‌

Si, après avoir vérifié que tous vos fichiers sont inclus dans le SUMMARY.md fichier, rien ne se passe encore sur GitBook, n'hésitez pas à contacter le support pour obtenir de l'aide.

L'aperçu GitHub ne s'affiche pas

Si l'aperçu GitHub ne s'affiche pas, cela peut être dû au fait que votre intégration GitSync a été configurée avant janvier 2022. Les versions de GitSync configurées avant cette date n'incluent pas l'Aperçu GitHub.

Vous auriez dû recevoir une notification vous demandant d'accepter une demande d'autorisation mise à jour pour activer l'accès en lecture seule aux PRs.

Si vous n'avez pas reçu la notification, pour résoudre le problème, vous devez mettre à jour vers la nouvelle version :

1. Désinstallez l'intégration GitSync de votre organisation.

2. Réinstallez la nouvelle version avec les autorisations mises à jour.

Veuillez noter que la désinstallation de l'intégration GitSync nécessitera de reconfigurer l'intégration sur tous les espaces auxquels elle était précédemment connectée.

Comptes potentiellement dupliqués lors de la connexion

Cette erreur se produit généralement lorsque le compte GitHub que vous utilisez pour configurer la synchronisation est déjà associé à un autre compte utilisateur GitBook.

Un bon moyen d'identifier à quel compte GitBook le compte GitHub est déjà lié est :

1. Déconnectez-vous de votre session utilisateur GitBook actuelle (c.-à-d. [e-mail])

2. Déconnectez-vous de toutes les sessions utilisateur GitHub.

3. Allez sur la page de connexion.

4. Sélectionnez l'option « Se connecter avec GitHub ».

5. Entrez vos identifiants GitHub.

6. Une fois connecté, allez dans les paramètres du compte et soit :

   1. Dissociez le compte depuis la section « Connexion tierce > GitHub » dans les paramètres personnels

   2. Supprimez complètement le compte si vous n'en avez pas besoin.

7. Déconnectez-vous de la session.

8. Reconnectez-vous en utilisant votre compte GitBook [e-mail].

9. Essayez de configurer à nouveau Git Sync.