Publier des articles sur GitBook
Connectez GitBook avec une clé d'accès personnelle et publiez des articles Clevera sous forme de pages dans vos espaces GitBook. Découvrez où créer la clé, comment choisir les sites, comment les astuces, les étapes et les onglets sont convertis, ce que fait la mise à jour et les erreurs courantes.
Publiez un article Clevera en tant que page dans un espace GitBook. GitBook se connecte à l'aide d'une clé d'accès personnelle au lieu d'une connexion classique, et la page apparaît au niveau supérieur de l'espace que vous choisissez.
Avant de commencer
- Dans Clevera : l'espace de travail doit être sous le forfait Pro ou Personnalisé, et vous devez être propriétaire ou administrateur pour connecter GitBook. Une fois connecté, toute personne pouvant modifier un article peut le publier. Voir Publier des articles sur vos autres outils.
- Dans GitBook : n'importe quel forfait. La clé agit en tant qu'utilisateur GitBook qui l'a créée ; cette personne doit donc disposer d'un accès en modification aux espaces sur lesquels vous publiez.
- Un article : générez-le d'abord. La publication n'envoie que l'article. Pour inclure une vidéo, placez-la à l'intérieur de l'article ; voir Afficher une vidéo dans un article.
Créer une clé d'accès GitBook
- Dans GitBook, ouvrez les paramètres de votre compte et accédez à Developer (
app.gitbook.com/account/developer). - Créez un nouveau jeton d'accès personnel, donnez-lui un nom tel que « Clevera » et copiez-le. GitBook ne l'affiche qu'une seule fois.
Connecter GitBook
Ouvrir la fenêtre de connexion
Dans Clevera, cliquez sur le nom de votre espace de travail dans la barre latérale, choisissez Intégrations, trouvez GitBook et cliquez sur Connecter. La fenêtre Connecter GitBook indique « Collez une clé. Nous la vérifions avant d'enregistrer quoi que ce soit. » et contient un lien Ouvrir GitBook vers la page Developer.
Coller et vérifier la clé
Collez la clé dans Clé d'accès et cliquez sur Vérifier la clé. Lorsque GitBook l'accepte, vous voyez « Clé acceptée. »
Choisir les sites
Sous Sites de publication, Clevera liste vos sites de documentation (ou espaces) et les sélectionne tous. Ouvrez la liste pour décocher ceux que vous ne voulez pas, par exemple « 2 sur 3 sélectionnés », puis cliquez sur Connecter. Vous verrez « GitBook connecté. ».
Clevera vérifie la clé avant d'enregistrer quoi que ce soit.
Si votre compte GitBook ne contient aucun espace, Clevera en crée un nommé « Clevera » dans votre première organisation afin que vous puissiez publier immédiatement.
La clé n'expire pas du côté de Clevera. Pour modifier la clé ou les sites, ouvrez le menu ⋯ sur la connexion GitBook, choisissez Reconnecter et suivez la même procédure ; la nouvelle clé et les nouveaux choix remplaceront les anciens.
Publier un article sur GitBook
Ouvrir l'onglet Publier
Dans l'éditeur, cliquez sur Partager → Publier et cliquez sur la tuile GitBook sous Prêt à publier.
Choisir un espace
Sous Où cela va, la liste affiche les espaces derrière les sites que vous avez choisis, avec leurs icônes.
Publier
Cliquez sur Publier sur GitBook. Clevera recherche d'abord une copie existante ; si une page portant le même titre se trouve déjà dans l'espace, choisissez quoi faire (voir Mettre à jour une page que vous avez publiée). Une fois terminé, vous verrez « Publié sur GitBook. » Cliquez sur Ouvrir dans GitBook pour voir la page.
Vous pouvez fermer la fenêtre Partager pendant l'exécution ; une notification vous avertit lorsque c'est terminé.
La page est ajoutée au niveau supérieur de l'espace, et son adresse provient du titre : « Set up billing » devient /set-up-billing. Les titres dans d'autres écritures ou avec des accents sont d'abord épelés en lettres latines ; un titre sans rien à épeler reçoit un court code fixe. Déplacez ou renommez la page dans GitBook par la suite si vous le souhaitez.
À quoi ressemble la page dans GitBook
Le titre de la page est le titre de l'article. La page ne contient que l'article : la vidéo dont provient l'article n'est pas ajoutée.
| Dans Clevera | Dans GitBook |
|---|---|
| Titres, paragraphes | Titres et texte |
| Gras, italique, barré, code en ligne, liens | Conservés |
| Surlignage, exposant, indice | Conservés |
| Listes à puces et numérotées, listes de tâches | Listes et listes de tâches |
| Citations | Citations |
| Blocs de code | Blocs de code avec le langage et le titre du code |
| Séparateurs | Séparateurs |
| Tableaux | Tableaux avec le texte de chaque cellule |
| Callouts | Blocs d'astuces : info → Info, note → Info, tip → Success, success → Success, warning → Warning, danger → Danger |
| Étapes numérotées | Un stepper GitBook, une étape par étape |
| Onglets | Onglets GitBook |
| Sections repliables | Blocs extensibles |
| Cartes | Une liste de liens avec leurs descriptions ; les icônes de carte sont omises |
| Équations | Mathématiques GitBook |
| Captures d'écran | Images téléchargées dans l'espace, avec la légende |
| Vidéos et intégrations dans l'article | Blocs d'intégration. Une vidéo Clevera n'est incluse que lorsque le lien de partage de cette vidéo est activé. |
Les captures d'écran sont téléchargées dans l'espace en tant que fichiers, elles continuent donc de fonctionner même si vous supprimez l'article dans Clevera. Un fichier vidéo téléchargé dans l'article reste un lien vers Clevera qui expire après un certain temps ; publiez à nouveau pour le renouveler.
Mettre à jour une page que vous avez publiée
La publication ne se fait que dans un sens. La page GitBook ne se met pas à jour lorsque vous modifiez l'article dans Clevera, et les modifications effectuées dans GitBook ne reviennent jamais dans Clevera. Après avoir modifié l'article, publiez-le à nouveau dans le même espace. Clevera recherche une page avec le même titre (la casse n'a pas d'importance) ou la même adresse et affiche « Cet article est déjà dans GitBook. »
- Mettre à jour l'article existant écrase le contenu et le titre de cette page. L'adresse reste la même. Les modifications apportées dans GitBook depuis sont écrasées ; l'historique de GitBook vous permet de les récupérer. Cliquez sur Mettre à jour dans GitBook.
- Créer un nouvel article ajoute une deuxième page sous le Nouveau titre que vous saisissez (Clevera en suggère un tel que « Set up billing (2) »), avec sa propre adresse. Cliquez sur Créer un nouvel article.
Déconnecter et révoquer l'accès
- Dans Clevera, ouvrez Intégrations, cliquez sur GitBook, puis sur Déconnecter et confirmez. Les pages que vous avez déjà publiées restent dans GitBook.
- Dans GitBook, supprimez la clé d'accès sur la page Developer afin qu'elle ne puisse plus être utilisée.
Dépannage
| Vous voyez | Que faire |
|---|---|
| « Collez d'abord une clé. » | Le champ de clé est vide. |
| « Clé d'accès GitBook invalide. Veuillez vérifier et réessayer. » | La clé est erronée ou a été supprimée. Créez-en une nouvelle et collez-la. |
| « Échec de la validation de la clé d'accès GitBook. » ou « Nous n'avons pas pu vérifier cette clé. Réessayez. » | GitBook n'a pas répondu. Réessayez dans un instant. |
| « Choisissez au moins un site. » | Cochez au moins un site avant Connecter. |
| « Aucun espace ou site de documentation GitBook trouvé, et nous n'avons pas pu en créer un automatiquement. Veuillez créer un espace dans GitBook et réessayer. » | Créez un espace dans GitBook, puis reconnectez-vous. |
| « Échec de la connexion à GitBook. Veuillez vérifier votre clé d'accès. » | Vérifiez la clé et reconnectez-vous. |
| « Impossible de charger vos espaces GitBook. Veuillez réessayer. » | Cliquez sur Réessayer. Si cela se répète, reconnectez GitBook. |
| « Veuillez sélectionner un espace sur lequel publier. » | Choisissez d'abord un espace. |
| Un espace est absent de la liste | Il ne fait pas partie des sites que vous avez choisis, ou l'utilisateur de la clé ne peut pas le voir. Reconnectez-vous et choisissez le site. |
| « GitBook a rejeté le contenu de la page » ou « GitBook n'a pas pu fusionner la demande de modification », avec la raison de GitBook | L'utilisateur de la clé ne peut pas modifier cet espace, ou GitBook a refusé la modification. Vérifiez l'accès dans GitBook, puis cliquez sur Réessayer. |
| « Clé d'accès introuvable. Veuillez reconnecter GitBook. » | Reconnectez GitBook avec une clé. |
| « Le contenu de l'article est vide ou invalide. » | L'article n'a pas encore de contenu. Ouvrez-le, vérifiez-le, puis publiez. |
| « La page à remplacer n'a pas été trouvée dans GitBook. Elle a peut-être été déplacée ou supprimée. » | Choisissez plutôt Créer un nouvel article. |
| « Échec de la publication sur GitBook. Veuillez réessayer. » ou « Échec de la mise à jour de la page dans GitBook. Veuillez réessayer. » | Cliquez sur Réessayer. Si cela continue d'échouer, reconnectez-vous avec une nouvelle clé. |