Was macht ein GitHub README Badge nützlich?
Ein GitHub README Badge ist ein kleines Bild, meist neben dem Projekttitel, das einen überprüfbaren Fakt zeigt. Build-Status, Paketversion, Lizenz, Dokumentation und Testabdeckung sind typische Beispiele. Das Bild allein ist nicht der Beleg; der Link muss zur Quelle führen.
Gute Badges reduzieren Unsicherheit bei Menschen, die ein Repository installieren, verwenden, unterstützen oder ihm vertrauen wollen. Ein Workflow-Badge zeigt, ob wichtige Prüfungen erfolgreich sind. Ein Release-Badge zeigt, ob das Projekt gepflegt wird. Ein Lizenz-Badge führt zu den Bedingungen für die Wiederverwendung.
Verwechsle README Badges nicht mit GitHub Achievements, Profile Trophy oder Beitragsgrafiken. Der GitHub-Achievements-Leitfaden erklärt offizielle Profil-Badges; der Leitfaden zu Profile-README-Ideen zeigt, wie Badges die Projektbelege unterstützen, statt sie zu verdecken.
Die erste Reihe sollte auf dem Smartphone schnell lesbar sein. Wenn Leser erst an zehn farbigen Badges vorbei müssen, bevor sie den Projekttext sehen, wird die Dekoration zum Hindernis. Behalte zuerst die Fakten, die die nächste Entscheidung beeinflussen.
Markdown-Syntax für GitHub README Badges
Die meisten GitHub README Badges verwenden normale Markdown-Bildsyntax. Die Bild-URL kommt zuerst; ein Link um das Bild führt zur Belegseite. Verwende einen kurzen, verständlichen Alt-Text, damit die Bedeutung auch ohne Bild erkennbar bleibt.
Shields.io kann Badges aus unterstützten Diensten oder aus festen Labels und Werten erzeugen. Verwende das dokumentierte Endpoint-Format statt URL-Parameter zu erraten. Wenn sich eine API ändert, kann eine geratenen URL ein defektes oder veraltetes Badge erzeugen.
Das Beispiel verlinkt ein Build-Badge mit der Workflow-Seite. Ersetze Repository und Endpoint und öffne das README abgemeldet, um Bild und Ziel zu prüfen.
[](https://github.com/your-name/your-repo/actions)| Typ | Typische Markdown-Quelle | Was es belegen soll |
|---|---|---|
| Build | Workflow- oder CI-Endpoint | Ob die geprüften Checks für Branch oder Kontext erfolgreich sind. |
| Release | aktuelle Release oder Paketversion | Welche Version Leser prüfen oder installieren sollten. |
| Lizenz | Lizenz-Badge des Repositorys | Wo die Nutzungsbedingungen vor einer Wiederverwendung stehen. |
| Dokumentation | Docs- oder API-Referenz-Link | Ein direkter Weg zu Einrichtung und Nutzung. |
| Coverage | Endpoint eines Coverage-Dienstes | Ein Testsignal nur dann, wenn die Metrik gepflegt und erklärt ist. |
Ein Pflege-Workflow für GitHub README Badges
Badges einzufügen ist leicht; sie korrekt zu halten ist die eigentliche Arbeit. Prüfe die Reihe, wenn Provider, Branch, Paketname, Release-Prozess, Dokumentation oder Lizenz geändert werden. Ein vor sechs Monaten korrektes Badge kann nach einer Migration irreführend sein.
Schreibe vor jedem neuen Bild den Satz auf, den es unterstützen soll. „Es sieht professionell aus“ ist kein guter Grund. „Ein Leser kann die aktuelle Version ohne Suche im Repository prüfen“ ist eine klare Aufgabe.
Der Profile-README-Vorlagenleitfaden hilft bei der Reihenfolge von Projektbelegen und visuellen Elementen. Wenn daneben Aktivitätskarten stehen, vergleiche sie mit dem GitHub-README-Stats-Leitfaden, damit keine Zahl doppelt dargestellt wird.
Die Leserfrage wählen
Entscheide, ob es um Build, Release, Lizenz, Dokumentation, Kompatibilität oder Qualität geht. Beginne nicht mit einer Farbsammlung.
Die Quelle prüfen
Nutze offiziellen Workflow, Paketregister, Lizenzdatei, Dokumentation oder einen gepflegten Metrik-Provider.
Bild und Link einfügen
Verwende Markdown, einen hilfreichen Alt-Text und den Link zur Quelle. Halte den Code für die nächste Pflege verständlich.
Das gerenderte README testen
Öffne die Repository-Seite am Desktop und auf dem Smartphone. Prüfe Bilder, Ziele, Kontrast und Umbruch.
Nach Änderungen erneut prüfen
Kontrolliere Badges nach Änderungen an Branch, CI, Paket, Release, Dokumentation oder Lizenz und entferne alte Angaben.
Welche GitHub README Badges solltest du wählen?
Es gibt keine universelle beste Badge-Reihe. Entscheidend ist, welche Entscheidung Leser treffen müssen. Eine Bibliothek braucht vielleicht Release, Paket, Lizenz, Dokumentation und CI. Ein Portfolio-Projekt kommt eventuell mit Demo, Deployment-Status und einer kurzen technischen Erklärung aus.
Halte die Themenbegrenzung bei README Badges. Repository-Badges, Profil-Achievements, Profile Trophy, Beitragsgrafiken und README Stats erfüllen andere Suchabsichten und sollten getrennte Leitfäden oder unterstützende Links bleiben.
Build-Status
Sinnvoll, wenn Tests oder Deployment für Leser wichtig sind. Verlinke Checks oder Workflow statt nur die Repository-Startseite.
Release oder Paket
Zeige eine aktuelle Quelle, wenn Leser wissen müssen, was sie installieren oder prüfen sollen. Pflege die Versionsnummer nicht doppelt.
Lizenz
Behalte sie, wenn Nutzungsrechte wichtig sind, und verlinke die tatsächliche Lizenzdatei.
Dokumentation
Für Bibliotheken, APIs und Tools nützlich, wenn das Badge zu einer gepflegten Start- oder Referenzseite führt.
Coverage oder Qualität
Nur zeigen, wenn Bedeutung und Provider klar sind. Eine Zahl ohne Kontext kann Vertrauen vermindern.
GitHub README Badge-Fehler beheben
Wenn ein Badge nicht rendert oder nicht mehr stimmt, prüfe zuerst die Quelle statt sofort den Provider zu wechseln. Diese Tabelle deckt häufige Markdown- und Pflegefehler ab.
| Problem | Wahrscheinliche Ursache | Lösung |
|---|---|---|
| Das Bild ist defekt | Endpoint, Pfad, Query oder Provider wurde geändert. | Öffne die Bild-URL direkt, lies die Dokumentation und aktualisiere oder entferne das Badge. |
| Das Bild ist veraltet | Ein manueller Wert oder eine alte Release-URL steht noch im README. | Verlinke eine lebende Quelle und vergleiche sie mit Release, Workflow oder Paket. |
| Der Link führt falsch | Der Markdown-Link wurde aus einem anderen Repository kopiert. | Öffne das Ziel abgemeldet und verlinke genau die Belegseite. |
| Die Reihe ist mobil zu breit | Zu viele Badges, lange Labels oder eine breite Tabelle. | Behalte entscheidende Badges, verschiebe Details nach unten und teste eine schmale Breite. |
| Private Daten sind nicht sichtbar | Der Provider kann ein privates Repository nicht lesen. | Nutze eine öffentliche Quelle, erkläre die Grenze oder entferne das Badge. |
| Das README wirkt wie eine Widget-Wand | Badges, Stats, Streaks und Achievements wiederholen dieselbe Aussage. | Projektbelege zuerst zeigen und nur unterschiedliche Signale behalten. |
FAQ zu GitHub README Badges
Wie füge ich Badges in ein GitHub README ein?
Füge ein Markdown-Bild ein und verlinke es bei Bedarf mit Workflow, Release, Lizenz oder Dokumentation. Prüfe danach die veröffentlichte Repository-Seite.
Welche Badges sind für ein Projekt sinnvoll?
Wähle Badges, die eine echte Frage zu Build, Release, Paket, Lizenz, Dokumentation oder einer gepflegten Qualitätsmetrik beantworten. Eine kurze Reihe reicht meist.
Kann ich Badges in einem Profile README nutzen?
Ja, aber Identität und Projektbelege müssen zuerst kommen. Der Leitfaden zu Profile-README-Ideen erklärt, wie du eine Widget-Wand vermeidest.
Sind README Badges GitHub Achievements?
Nein. README Badges sind vom Autor gewählte Markdown-Bilder; Achievements sind offizielle Profil-Badges von GitHub.
Soll ich überall Shields.io verwenden?
Nein. Nutze dokumentierte, stabile Endpoints, aber den offiziellen Anbieter, wenn dessen Quelle verständlicher ist, und vermeide doppelte Angaben.
Wie viele Badges braucht ein README?
Es gibt keine feste Zahl. Starte mit dem kleinsten Satz, der Installation, Vertrauen oder Beitrag unterstützt, und entferne Dekoration und veraltete Angaben.