Qu’est-ce qui rend un badge README GitHub utile ?
Un badge README GitHub est une petite image, souvent placée près du titre du projet, qui communique un fait vérifiable. Le statut du build, la version, la licence, la documentation et la couverture sont des exemples courants. L’image ne suffit pas : le lien doit permettre d’inspecter la source.
Les bons badges réduisent l’incertitude d’une personne qui veut installer, utiliser, contribuer ou faire confiance à un dépôt. Un badge de workflow peut montrer que les vérifications principales passent ; un badge de release indique l’activité du projet ; un badge de licence aide à trouver les conditions de réutilisation.
Ne confondez pas les badges README avec GitHub Achievements, Profile Trophy ou les visuels de contributions. Le guide GitHub Achievements traite les badges officiels du profil, tandis que le guide des idées de Profile README explique comment garder la preuve du projet au premier plan.
La première rangée doit rester lisible sur téléphone. Si un visiteur doit traverser dix badges avant de voir l’explication du projet, la décoration masque le contenu. Gardez d’abord les faits qui changent la décision suivante et déplacez le reste plus bas.
Syntaxe Markdown des badges GitHub
La plupart des badges README GitHub utilisent la syntaxe d’image Markdown. L’URL de l’image vient en premier ; le lien autour de l’image permet ensuite d’ouvrir la preuve. Utilisez un texte alternatif court et explicite lorsque l’image ne se charge pas.
Shields.io peut créer des badges depuis des services compatibles ou des valeurs personnalisées. Utilisez le format documenté par le fournisseur au lieu de deviner les paramètres. Une API qui change peut transformer une URL supposée en image cassée ou en information périmée.
L’exemple relie un badge de build à la page du workflow. Remplacez le dépôt et l’endpoint, puis ouvrez le README déconnecté pour vérifier que l’image et la destination sont publiques.
[](https://github.com/your-name/your-repo/actions)| Type | Source Markdown habituelle | Ce que le badge doit prouver |
|---|---|---|
| Build | endpoint de workflow ou CI | Si les contrôles passent pour la branche ou le contexte indiqué. |
| Release | dernière release ou version du paquet | Quelle version le lecteur doit examiner ou installer. |
| Licence | badge de licence du dépôt | Où consulter les autorisations avant de réutiliser le code. |
| Documentation | lien vers docs ou référence API | Un accès direct à la configuration et à l’utilisation. |
| Couverture | endpoint d’un service de couverture | Un signal de test seulement si la métrique est entretenue et expliquée. |
Un flux de maintenance pour les badges README
Ajouter des badges est simple ; les garder exacts est le vrai travail. Réexaminez la rangée après un changement de fournisseur, de branche, de paquet, de processus de release, de documentation ou de licence. Un badge exact il y a six mois peut devenir trompeur après une migration.
Avant d’ajouter une image, écrivez la phrase qu’elle doit soutenir. Si cette phrase est « cela fait professionnel », le badge est probablement inutile. Si elle est « le lecteur peut vérifier la version actuelle sans chercher dans le dépôt », le badge a une fonction claire.
Le guide du modèle Profile README aide à placer les preuves du projet et les visuels dans le bon ordre. Si des cartes d’activité sont proches, consultez le guide GitHub README Stats pour ne pas répéter le même signal.
Choisir la question du lecteur
Décidez si le badge concerne le build, la release, la licence, la documentation, la compatibilité ou la qualité. Ne commencez pas par une collection décorative.
Trouver la source de vérité
Utilisez le workflow officiel, le registre de paquets, le fichier de licence, le site de documentation ou un fournisseur entretenu.
Ajouter l’image et le lien
Employez la syntaxe Markdown, un alt utile et un lien vers la preuve. Gardez le code lisible pour la prochaine maintenance.
Vérifier le README rendu
Ouvrez la page du dépôt sur ordinateur et mobile. Contrôlez les images, les destinations, le contraste et le retour à la ligne.
Revoir après les changements
Contrôlez les badges après un changement de branche, de CI, de paquet, de release, de documentation ou de licence.
Quels badges README GitHub choisir ?
Il n’existe pas de liste universelle. Choisissez selon la décision que le lecteur doit prendre. Une bibliothèque peut utiliser release, paquet, licence, documentation et CI. Un projet de portfolio peut se contenter d’une démo, d’un statut de déploiement et d’une courte explication technique.
Gardez la frontière du sujet sur les badges README. Les badges de dépôt, les achievements du profil, Profile Trophy, les graphiques de contributions et README Stats répondent à d’autres intentions et doivent rester des guides distincts ou des liens de soutien.
Statut du build
Utile lorsque les tests ou le déploiement comptent. Liez-le aux checks ou au workflow, pas seulement à l’accueil du dépôt.
Release ou paquet
Montrez une source actuelle quand le lecteur doit savoir quoi installer ou examiner. Évitez de saisir le numéro à deux endroits.
Licence
Gardez ce badge lorsque les droits de réutilisation comptent et liez-le au fichier de licence réel.
Documentation
Un badge de documentation convient aux bibliothèques, API et outils s’il mène à un guide ou une référence maintenue.
Couverture ou qualité
Affichez la métrique seulement si son sens est clair et le fournisseur stable. Un chiffre sans contexte peut diminuer la confiance.
Dépanner un badge README GitHub
Quand un badge ne s’affiche plus ou ne dit plus vrai, examinez la source avant de changer de fournisseur. Ces vérifications couvrent les problèmes Markdown et de maintenance les plus courants.
| Problème | Cause probable | Correction |
|---|---|---|
| L’image est cassée | L’endpoint, le chemin, la requête ou le fournisseur a changé. | Ouvrez l’URL directement, consultez la documentation et mettez à jour ou supprimez le badge. |
| L’image est périmée | Une valeur manuelle ou une ancienne URL de release est encore utilisée. | Pointez vers une source vivante et comparez-la avec la release, le workflow ou le paquet. |
| Le lien ouvre la mauvaise page | Le lien Markdown d’un autre dépôt a été copié. | Testez la destination déconnecté et liez la preuve exacte. |
| La rangée déborde sur mobile | Trop de badges, des libellés longs ou une table large. | Gardez les badges décisifs, déplacez le reste plus bas et testez une petite largeur. |
| Une métrique privée est invisible | Le fournisseur ne peut pas lire le dépôt privé. | Utilisez une source publique, expliquez la limite ou retirez le badge. |
| Le README ressemble à un mur de widgets | Badges, stats, streaks et achievements répètent le même signal. | Placez les preuves du projet en premier et gardez seulement les signaux différents. |
FAQ sur les badges README GitHub
Comment ajouter des badges à un README GitHub ?
Ajoutez une image Markdown puis, si nécessaire, un lien vers le workflow, la release, la licence ou la documentation. Contrôlez ensuite la page publique du dépôt.
Quels badges sont utiles pour un projet ?
Choisissez ceux qui répondent à une question réelle : build, release, paquet, licence, documentation ou métrique entretenue. Une rangée courte est généralement préférable.
Peut-on mettre des badges dans un Profile README ?
Oui, mais ils doivent rester secondaires par rapport à l’identité et aux projets. Le guide des idées de Profile README explique comment éviter un mur de widgets.
Les badges README sont-ils des GitHub Achievements ?
Non. Les premiers sont des images Markdown choisies par l’auteur ; les Achievements sont des badges officiels du profil gérés par GitHub.
Faut-il utiliser Shields.io partout ?
Non. Utilisez ses endpoints documentés et stables, mais gardez un fournisseur officiel lorsqu’il rend la source plus lisible et évitez les doublons.
Combien de badges faut-il dans un README ?
Il n’y a pas de nombre fixe. Commencez par le minimum utile pour installer, faire confiance ou contribuer, puis supprimez ce qui est décoratif ou obsolète.