Publier des articles sur ReadMe
Connectez un projet ReadMe avec sa Clé API et publiez des articles Clevera sous forme de guides dans la catégorie de votre choix, avec des captures d'écran importées sur ReadMe. Découvrez comment les encadrés, les étapes et les vidéos sont convertis, comment fonctionnent les mises à jour et les erreurs courantes.
Publiez un article Clevera en tant que guide dans votre projet ReadMe, classé dans la catégorie de guide que vous choisissez. Les captures d'écran sont importées sur ReadMe.
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 ReadMe. Une fois connecté, toute personne pouvant modifier un article peut le publier. Voir Publier des articles sur vos autres outils.
- Dans ReadMe : un projet que vous pouvez gérer, avec au moins une catégorie dans sa section Guides. Une clé permet de connecter un projet.
- Un projet ReadMe actuel : Clevera publie via l'API actuelle (v2) de ReadMe, que ReadMe propose aux projets sur ReadMe Refactored. Les projets toujours sur l'ancienne plateforme de ReadMe ne peuvent pas être connectés.
- Version : Clevera publie vers la version principale (stable) des Guides de votre projet.
- Un article : générez-le d'abord. La publication envoie uniquement l'article. Pour inclure une vidéo, placez-la à l'intérieur de l'article ; voir Afficher une vidéo dans un article.
Trouver votre Clé API ReadMe
Dans votre projet ReadMe, ouvrez Configuration → API Keys, puis copiez une clé (créez-en une si la liste est vide). La clé donne un accès complet à ce projet, gardez-la donc privée.
Connecter ReadMe
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 ReadMe et cliquez sur Connecter. La fenêtre Connecter ReadMe indique "Collez une clé. Nous la vérifions avant d'enregistrer quoi que ce soit."
Coller et vérifier la clé
Collez la clé dans Clé API et cliquez sur Vérifier la clé. Lorsque ReadMe l'accepte, vous voyez "Clé acceptée." et votre projet sous Sites de publication.
Connecter
Cliquez sur Connecter. Vous voyez "ReadMe connecté." et ReadMe apparaît sous Connecté avec le nom de votre projet.
La clé n'expire pas du côté de Clevera. Pour connecter un projet différent, utilisez Reconnecter sur la connexion ReadMe et collez la clé de ce projet ; elle remplace l'ancienne.
Publier un article sur ReadMe
Ouvrir l'onglet Publier
Dans l'éditeur, cliquez sur Partager → Publier et cliquez sur la tuile ReadMe sous Prêt à publier.
Choisir une catégorie de guide
Sous Où cela va, Projet affiche le projet connecté. Choisissez une Catégorie de guide : "L'article va dans la section Guides, sous cette catégorie." Si vous voyez "Aucune catégorie de guide pour le moment", créez-en une dans ReadMe d'abord.
Publier
Cliquez sur Publier sur ReadMe. Clevera recherche d'abord une copie existante ; si un guide avec la même adresse existe déjà, choisissez quoi faire (voir Mettre à jour un guide). Une fois terminé, vous voyez "Publié sur ReadMe." Cliquez sur Ouvrir dans ReadMe pour voir le guide.
Vous pouvez fermer la fenêtre Partager pendant l'opération ; une notification vous indique quand elle est terminée.
L'adresse du guide provient de son titre : "Set up billing" devient /docs/set-up-billing sur votre site de documentation. Les titres dans d'autres écritures ou avec des accents sont d'abord transcrits en lettres latines. Si l'adresse est déjà prise, ReadMe en attribue une légèrement différente au nouveau guide.
À quoi ressemble le guide dans ReadMe
Le titre du guide est le titre de l'article. Le guide contient uniquement l'article : la vidéo dont provient l'article n'est pas ajoutée.
| Dans Clevera | Dans ReadMe |
|---|---|
| Titres, paragraphes | Titres et texte |
| Gras, italique, barré, code en ligne, liens | Conservés. Les liens vers d'autres pages Clevera conservent uniquement leur texte. |
| Surlignage, exposant, indice | Conservés |
| Listes à puces et numérotées, listes de contrôle | Listes et listes de contrôle |
| 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 |
| Encadrés | Encadrés ReadMe avec le titre de l'encadré : 📘 pour info et note, 👍 pour astuce et succès, 🚧 pour avertissement, ❗️ pour danger |
| Étapes numérotées | Une liste numérotée : le titre de chaque étape en gras, son contenu imbriqué en dessous |
| Onglets | L'étiquette de chaque onglet en gras, suivie de son contenu. Les onglets contenant uniquement du code deviennent des onglets de code ReadMe. |
| Sections repliables | Sections extensibles |
| Cartes | Une liste de liens avec leurs descriptions ; les icônes de carte sont omises |
| Équations | Code |
| Captures d'écran | Images importées sur ReadMe, avec la légende en italique |
| Vidéos et intégrations dans l'article | Intégrations ReadMe. Une vidéo Clevera est incluse uniquement lorsque le lien de partage de cette vidéo est activé. |
Les accolades et les chevrons dans votre texte sont échappés, afin que le format de page de ReadMe les affiche tels qu'ils sont écrits.
Les captures d'écran sont importées sur ReadMe, elles continuent donc de fonctionner même si vous supprimez l'article dans Clevera. Une capture d'écran qui ne parvient pas à être importée, ou un fichier vidéo à l'intérieur de l'article, reste un lien vers Clevera qui expire après un certain temps ; publiez à nouveau pour le renouveler.
Mettre à jour un guide
La publication est à sens unique. Le guide ne se met pas à jour lorsque vous modifiez l'article dans Clevera, et les modifications effectuées dans ReadMe ne reviennent jamais dans Clevera. Après avoir modifié l'article, publiez-le à nouveau.
Clevera recherche un guide avec la même adresse n'importe où dans vos Guides et affiche "Cet article est déjà dans ReadMe." Cliquez sur Le voir pour l'ouvrir, puis choisissez :
- Mettre à jour l'article existant écrase ce guide : même adresse, nouveau titre et nouveau contenu. Cliquez sur Mettre à jour dans ReadMe.
- Créer un nouvel article crée un nouveau guide sous le Nouveau titre que vous saisissez, avec sa propre adresse. Cliquez sur Créer un nouvel article.
Les modifications apportées dans ReadMe depuis la dernière publication sont écrasées lorsque Clevera met à jour un guide.
Déconnecter et révoquer l'accès
- Dans Clevera, ouvrez Intégrations, cliquez sur ReadMe, puis sur Déconnecter et confirmez. Les guides que vous avez déjà publiés restent dans ReadMe.
- Dans ReadMe, ouvrez Configuration → API Keys et supprimez la clé que vous avez donnée à Clevera.
Dépannage
| Vous voyez | Que faire |
|---|---|
| "Collez d'abord une clé." | Le champ de clé est vide. |
| "Clé API invalide. Veuillez vérifier votre Clé API ReadMe." | La clé est erronée ou a été supprimée. Copiez-la à nouveau depuis Configuration → API Keys. |
| "Échec de la récupération des informations du projet depuis ReadMe." ou "Nous n'avons pas pu vérifier cette clé. Réessayez." | ReadMe n'a pas répondu, ou le projet n'est pas sur ReadMe Refactored, ce dont Clevera a besoin. Réessayez, puis essayez une nouvelle clé ; si le projet est sur l'ancienne plateforme de ReadMe, il ne peut pas être connecté. |
| "Impossible de valider la Clé API. Veuillez vérifier votre Clé API ReadMe." ou "Échec de la connexion à ReadMe. Veuillez vérifier votre Clé API." | Vérifiez la clé et connectez-vous à nouveau. |
| "Aucune catégorie de guide pour le moment" / "Créez une catégorie de guide dans ReadMe pour publier ici." | Ajoutez une catégorie à vos Guides dans ReadMe, puis rouvrez l'onglet Publier. |
| "Choisissez d'abord une catégorie." ou "Choisissez une catégorie ReadMe dans laquelle publier ce guide." | Choisissez une catégorie de guide avant de publier. |
| "Vous pouvez voir cet élément mais pas le publier. Demandez à quelqu'un qui peut le modifier." | Vous avez besoin d'un accès en modification à l'article pour le publier. |
| "Clé API introuvable. Veuillez reconnecter ReadMe." | Connectez ReadMe à nouveau 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. |
| "Impossible de publier sur ReadMe" avec un message de ReadMe, tel qu'un message concernant le slug ou la catégorie | ReadMe a refusé le guide. Vérifiez que la catégorie existe toujours, ou renommez l'article et cliquez sur Réessayer. |
| "Échec de la mise à jour du guide dans ReadMe" | Le guide que vous avez essayé de mettre à jour a été supprimé ou renommé dans ReadMe. Publiez à nouveau et choisissez Créer un nouvel article. |
| "Échec de la publication sur ReadMe. Veuillez réessayer." | Cliquez sur Réessayer. Si cela continue d'échouer, connectez-vous à nouveau avec une nouvelle clé. |