Medienperformance # Vier Wege für Bilder und Badges in GitHub-READMEs Fügen Sie Bilder über Repository-Dateien, Issue-Anhänge, Raw-URLs, HTML oder generierte Assets zu einem GitHub-README hinzu. Veröffentlicht am 11. August 2026 ## Wichtigste Erkenntnisse * Relative Repository-Pfade sorgen dafür, dass Dokumentation und zugehörige Assets gemeinsam versioniert werden. * URLs von Issue-Uploads sind praktisch, lassen sich aber weniger transparent prüfen und migrieren. * Externe URLs verkleinern das Repository, schaffen jedoch eine weitere Abhängigkeit bei Verfügbarkeit und Datenschutz. README-Bilder können im Repository gespeichert sein, eine GitHub-Anhangs-URL verwenden, auf öffentlichen Speicher verweisen oder für begrenzte Layoutkontrolle HTML nutzen. Welche Option am besten geeignet ist, hängt von Eigentümerschaft, Versionierung, Portabilität und Aktualisierungshäufigkeit ab. ## In diesem Leitfaden 1. [Bildspeicherort nach Eigentümerschaft und Lebensdauer auswählen](#images-in-github-readmes-section-1) 2. [Release-spezifische Medien im Repository verwalten](#images-in-github-readmes-section-2) 3. [Anhänge und externe Bilder als externe Abhängigkeiten behandeln](#images-in-github-readmes-section-3) 4. [Markdown für die Bedeutung und HTML nur für notwendige Layoutkontrolle verwenden](#images-in-github-readmes-section-4) 5. [Bilder für ihre tatsächliche Anzeigegröße vorbereiten](#images-in-github-readmes-section-5) 6. [Alternativtext passend zur Rolle des Bildes verfassen](#images-in-github-readmes-section-6) 7. [Grafiken für verschiedene Themes und fehlende Ressourcen robust gestalten](#images-in-github-readmes-section-7) 8. [Badges als Zusammenfassungen statt als maßgebliche Quelle verwenden](#images-in-github-readmes-section-8) 9. [Bilder im Rahmen der Dokumentationstests prüfen](#images-in-github-readmes-section-9) ## Worauf es besonders ankommt * HTML-Markup für Bilder kann Abmessungen festlegen, GitHub entfernt jedoch nicht unterstützte Elemente und Attribute. * Generierte Status-Badges sind nützlich, wenn ihr Dienst und das Fallback-Verhalten bekannt sind. ## Bildspeicherort nach Eigentümerschaft und Lebensdauer auswählen Ein README-Bild ist eine Abhängigkeit der Dokumentation. Bevor Sie eine URL auswählen, legen Sie fest, wem die Datei gehört, ob sie sich zusammen mit dem Code ändern muss, wie lange sie verfügbar bleiben soll und wo das README gerendert wird. Für ein versioniertes Architekturdiagramm gelten andere Anforderungen als für einen temporären Screenshot aus einem Pull Request oder ein Badge, das aus aktuellen Projektdaten erzeugt wird. Speichern Sie beispielsweise Installations-Screenshots neben dem README, wenn jedes Release eine andere Benutzeroberfläche dokumentiert. Ein Community-Logo, das in vielen Repositorys verwendet wird, kann stattdessen in einen zentral verwalteten öffentlichen Speicher gehören. Wählen Sie einen Speicherort nicht allein danach aus, ob er während der Bearbeitung bequem ist. Wenn Sie Bilder später verschieben, können alte Tags, Paketseiten, Forks und Links zu historischer Dokumentation beschädigt werden. ### Repository-Datei Am besten für Assets geeignet, die zusammen mit der Dokumentation geprüft, versioniert und veröffentlicht werden sollen. ### GitHub-Anhang Praktisch für Diskussionen und gelegentlich verwendete README-Medien, doch Eigentümerschaft und Migrationspfad sind weniger transparent als bei einer nachverfolgten Datei. ### Externe URL Nützlich für zentral verwaltete oder häufig geänderte Assets, schafft jedoch eine zusätzliche Abhängigkeit hinsichtlich Verfügbarkeit, Datenschutz und Zugriffskontrolle. ### Erzeugtes Bild Geeignet für nicht wesentliche Statusinformationen, sofern die Leser das Projekt auch verstehen können, wenn der Generator nicht verfügbar ist. ## Release-spezifische Medien im Repository verwalten Legen Sie eine nachverfolgte Datei in einem vorhersehbaren Verzeichnis wie `docs/images/` ab und referenzieren Sie sie mit Markdown, beispielsweise `![Settings screen](docs/images/settings.png)`. Durch relative Pfade werden README und Bild in Branches und Forks gemeinsam verschoben. Lösen Sie den Pfad vom Speicherort der Markdown-Datei aus auf, nicht vom Stammverzeichnis des Repositorys, da für ein README in einem Unterverzeichnis ein anderer Basispfad gilt. Behandeln Sie die Schreibweise von Pfaden wie Code. Unterschiede bei der Groß- und Kleinschreibung funktionieren möglicherweise im Dateisystem eines einzelnen Entwicklers, können aber andernorts zu Fehlern führen. Auch das Umbenennen eines Verzeichnisses, das Komprimieren eines Bildes oder das Löschen einer scheinbar ungenutzten Datei kann ältere Dokumente beschädigen. Prüfen Sie Bildänderungen zusammen mit dem davon abhängigen Text und verwenden Sie aussagekräftige Dateinamen statt undurchsichtiger Namen, die aus einem Screenshot-Tool übernommen wurden. Fixieren Sie Dokumentationsbilder auf eine stabile Revision, wenn die Seite eine veröffentlichte Benutzeroberfläche oder ein veröffentlichtes Verhalten beschreibt. Ein Branch-relativer Pfad ist während der Bearbeitung praktisch, doch dasselbe README kann nach einer Änderung des Branches andere Grafiken anzeigen. Release Notes, Sicherheitshinweise und versionierte Einrichtungsanleitungen profitieren von unveränderlichen Referenzen, weil die Leser dann das Bild sehen, das genau zu dieser Version gehörte, und nicht den neuesten Ersatz. ### Relativer Pfad In der Regel die am einfachsten zu pflegende Referenz für ein Bild, das zusammen mit dem README eingecheckt wurde. ### URL des Standard-Branches Folgt stets diesem Branch. Das ist für aktuelle Dokumentation nützlich, kann bei alten Referenzen jedoch dazu führen, dass neuere Grafiken angezeigt werden. ### An einen Commit gebundene URL Bietet eine unveränderliche Ansicht für Releases oder Audits, erfordert jedoch bewusste Aktualisierungen, wenn sich das Bild ändert. ## Anhänge und externe Bilder als externe Abhängigkeiten behandeln Wenn Sie ein Bild in einen GitHub-Editor ziehen, kann daraus eine URL zu einem gehosteten Anhang entstehen. Das geht schnell und vermeidet Binärdaten im Repository, doch das resultierende Asset ist nicht als normale Datei im Git-Verlauf enthalten. Dokumentieren Sie, warum die URL vorhanden ist, bewahren Sie das Original an einem kontrollierten Speicherort auf und stellen Sie sicher, dass das Team bei Repository-Übertragungen oder Dokumentationsmigrationen nicht ohne eine verwaltbare Quelldatei bleibt. Eine externe URL kann die Größe des Repositorys verringern und ermöglichen, dass ein Asset in mehreren Dokumenten zugleich aktualisiert wird. Sie kann jedoch auch ausfallen, etwa durch eine abgelaufene signierte URL, geänderte Zugriffsrichtlinien, ein gelöschtes Objekt, ein DNS-Problem oder eine Hotlink-Sperre. Verwenden Sie einen HTTPS-Speicherort, der für dauerhaften öffentlichen Zugriff vorgesehen ist, vergewissern Sie sich, dass die Weiterverbreitung zulässig ist, und betten Sie keine privaten Endpunkte ein. Auf github.com werden gerenderte Markdown-Bilder über den anonymisierenden Camo-Proxy von GitHub abgerufen. Dieser verbirgt Netzwerk- und Browserdetails der Leser vor dem Host, kann keine Bilder abrufen, die eine Authentifizierung oder ein privates Netzwerk erfordern, und kann nach einer Änderung der Quelle weiterhin eine zwischengespeicherte Kopie ausliefern. Renderer ohne Bild-Proxy können dem Host weiterhin Informationen über die Leser offenlegen. Datenschutzsensible Projekte sollten daher unnötige Ressourcen von Drittanbietern minimieren. ## Markdown für die Bedeutung und HTML nur für notwendige Layoutkontrolle verwenden Standard-Markdown ist die portable Standardeinstellung: `![alternative text](path-or-url)`. Es vermittelt den Zweck des Bildes und funktioniert in mehr Repository-Browsern, Paketregistrys, Dokumentationsgeneratoren und lokalen Vorschauwerkzeugen. Optionale Hover-Titel sollten zweitrangig bleiben, da Nutzer von Tastaturen und Touch-Geräten sie möglicherweise nie sehen und ein Titel weder den Alternativtext noch eine sichtbare Erklärung ersetzt. Mit einem HTML-Element `img` lassen sich Abmessungen festlegen, wenn ein Screenshot die Seite sonst dominiert. GitHub bereinigt nicht unterstütztes HTML sowie nicht unterstützte Attribute und Stile. Aufwendige Positionierungen können daher verschwinden oder sich anders als in einer lokalen Vorschau verhalten. Bevorzugen Sie ein einfaches Element mit `src`, `alt`, `width` und `height`. Base64-Daten-URLs machen Markdown umfangreich, schwer zu prüfen und schlecht portierbar. Außerdem verhindern sie das normale Caching von Dateien und sollten nicht die übliche Lösung für die Asset-Verwaltung sein. Für ein Inhaltsbild prägnantes Markdown bevorzugen ``` ![Diagram showing the request flow from the browser through the API to object storage](docs/request-flow.png) ``` HTML nur verwenden, wenn das README-Layout es erfordert ```

Dashboard showing three completed uploads

``` ## Bilder für ihre tatsächliche Anzeigegröße vorbereiten Committen Sie keine Desktop-Aufnahme in voller Auflösung, wenn das README sie in einer schmalen Inhaltsspalte anzeigt. Passen Sie ihre Größe ungefähr an die sinnvolle Lesebreite an und behalten Sie zugleich eine ausreichende Pixeldichte für scharfen Text auf hochauflösenden Displays bei. Die Komprimierung sollte unnötige Daten entfernen, ohne Beschriftungen der Benutzeroberfläche in Artefakte zu verwandeln. Vergleichen Sie das optimierte Ergebnis in seiner gerenderten Größe, statt nur die Dateigröße zu beurteilen. Wählen Sie das Format passend zum Inhalt. JPEG eignet sich für fotografische Bilder, die keine Transparenz benötigen. PNG bleibt für scharfe Aufnahmen von Benutzeroberflächen, Diagramme mit wenigen Farben und Transparenz nützlich, kann jedoch große Dateien erzeugen. WebP kann sich für gemischtes Bildmaterial eignen, wenn jeder vorgesehene Renderer getestet wurde. SVG ist für Diagramme und Logos geeignet, die als Vektorgrafiken erstellt wurden, doch veröffentlicht werden sollten nur vertrauenswürdige SVG-Dateien. Bewahren Sie für Diagramme eine bearbeitbare Quelldatei auf, auch wenn das README eine exportierte Rasterversion verwendet. ### Zuerst zuschneiden Entfernen Sie vor der Größenänderung Browserrahmen, leere Ränder und nicht relevante Anwendungsbereiche. ### Lesbarkeit erhalten Prüfen Sie kleine Beschriftungen, Terminaltext und dünne Diagrammlinien bei der endgültigen Anzeigebreite. ### Sensible Metadaten entfernen Prüfen Sie vor dem Committen Dateinamen, eingebettete Metadaten, sichtbare Kontodaten, Zugriffstoken und Benachrichtigungen. ### Wachstum des Repositorys begrenzen Das Ersetzen einer großen Binärdatei entfernt ihre früheren Versionen nicht aus dem Git-Verlauf. Optimieren Sie sie daher vor dem ersten Commit. ## Alternativtext passend zur Rolle des Bildes verfassen Der Alternativtext sollte vermitteln, was Leser in diesem Kontext aus dem Bild erfahren müssen. Beschreiben Sie bei einem Screenshot eines erfolgreichen Tests den relevanten Erfolgszustand, statt jedes sichtbare Bedienelement aufzuführen. Fassen Sie bei einem Diagramm die dargestellte Beziehung zusammen und erläutern Sie komplexe Details im umgebenden Text. Wiederholen Sie eine Bildunterschrift nicht Wort für Wort und verwenden Sie keinen Dateinamen wie `screen-final-2.png` als Beschreibung. Ein verlinktes Bild benötigt einen Text, der das Ziel oder die Aktion des Links vermittelt, nicht nur sein Aussehen. Dekorative Trennzeichen und wiederholte Markenlogos sollten leeren Alternativtext erhalten, sofern der Renderer dies zulässt. Status-Badges benötigen dagegen prägnante Beschriftungen wie `Build: passing`. Wesentliche Befehle, Konfigurationen oder Fehlermeldungen müssen außerdem als auswählbarer Text vorhanden sein, da Bilder kein zuverlässiges Kopieren, Suchen, Übersetzen oder Zoomen ermöglichen. ## Grafiken für verschiedene Themes und fehlende Ressourcen robust gestalten Transparente Logos und Diagramme setzen häufig eine weiße Fläche voraus. In einem dunklen Theme können schwarze Linien verschwinden, in einem hellen Theme weiße Beschriftungen. Testen Sie beide Themes und fügen Sie einen bewusst gewählten Hintergrund oder Rahmen hinzu, wenn ein einziges Asset für beide geeignet ist. Falls der Renderer Theme-spezifische Bildquellen unterstützt, halten Sie die helle und die dunkle Version semantisch gleichwertig und versehen Sie das Gesamtbild mit genau einem aussagekräftigen Alternativtext. Gestalten Sie den umgebenden Absatz so, dass das README verständlich bleibt, während ein Bild geladen wird oder nicht verfügbar ist. Platzieren Sie niemals den einzigen Installationsschritt, Sicherheitshinweis oder die einzige Kompatibilitätsanforderung in einem Screenshot. Vermitteln Sie Bedeutung nicht ausschließlich durch Farbe und prüfen Sie Diagramme bei stärkerem Zoom. Diese Verfahren fördern die Barrierefreiheit und machen die Dokumentation zugleich robuster in reinen Textwerkzeugen, zwischengespeicherten Paketseiten und eingeschränkten Netzwerken. ## Badges als Zusammenfassungen statt als maßgebliche Quelle verwenden Ein Badge ist ein extern erzeugtes Bild, das veränderliche Daten wie ein Build-Ergebnis, eine Paketversion oder einen Abdeckungsstatus zusammenfasst. Seine Genauigkeit hängt vom vorgelagerten Dienst, den Abfrageparametern, der Branch-Auswahl, der Authentifizierung, dem Caching und dem Aktualisierungsverhalten ab. Verlinken Sie das Badge mit einer Seite, auf der Leser das zugrunde liegende Ergebnis prüfen können, und beschriften Sie es so, dass seine Bedeutung ohne Interpretation der Farbe verständlich ist. Beschränken Sie die Badge-Zeile auf eine gezielte Auswahl. Eine lange Folge von Serviceaufrufen verlangsamt das Rendering, erzeugt visuelle Unruhe und erhöht die Zahl der Parteien, die beim Öffnen des README kontaktiert werden. Verwenden Sie ein Badge niemals als einzigen Hinweis auf ein Sicherheitsproblem oder eine unterstützte Version. Fällt ein Anbieter aus, sollten die Projektbeschreibung und der normale Workflow für Mitwirkende weiterhin verständlich sein. ## Bilder im Rahmen der Dokumentationstests prüfen Sehen Sie sich die Vorschau des README im GitHub-Renderer an, nachdem Sie die Änderungen in einen Branch committet haben. Öffnen Sie jedes Bild, überprüfen Sie die relativen Pfade vom tatsächlichen Speicherort des README aus, wechseln Sie zwischen den Farbschemata und kontrollieren Sie schmale sowie gezoomte Layouts. Wenn das README in einer Paketregistry oder auf einer Dokumentationswebsite veröffentlicht wird, testen Sie es auch dort, da sich die Regeln für relative URLs und das unterstützte HTML unterscheiden können. Ergänzen Sie einfache betriebliche Prüfungen für wichtige Assets. Ein Link-Checker kann fehlende Remote-Bilder erkennen, während eine Repository-Prüfung übergroße Binärdateien und nicht nachverfolgte Quelldateien aufdecken kann. Prüfen Sie Screenshots erneut, wenn sich die Oberfläche ändert, und entfernen Sie veraltete Assets erst, nachdem Sie alle Branches der weiterhin gepflegten Dokumentation durchsucht haben. Ziel ist nicht nur ein heute korrekt gerendertes Bild, sondern ein Dokument, das während der gesamten unterstützten Lebensdauer des Projekts verständlich bleibt. ### Darstellung Überprüfen Sie die Repository-Seite, Forks, Release-Tags, Paketspiegel und jede generierte Dokumentation, die das README verwendet. ### Barrierefreiheit Prüfen Sie Alternativtext, Textkontrast, das Verhalten in verschiedenen Farbschemata, die Zoomdarstellung und ob wesentliche Informationen auch außerhalb der Bilder verfügbar sind. ### Leistung Prüfen Sie codierte Abmessungen, Übertragungsgröße und Anzahl der Badges sowie die Notwendigkeit mehrerer Screenshots in voller Auflösung. ### Projektsteuerung Klären Sie Eigentümerschaft, Lizenz, bearbeitbare Quelldatei und Aktualisierungsverantwortung sowie einen Migrationsplan für extern gehostete Assets. ## Wissenswerte technische Details * Relative Bild-URLs werden auf einer Repository-Seite, in einer Paketregistry, in einer kopierten Markdown-Datei und in einem externen Dokumentations-Renderer unterschiedlich aufgelöst. Daher sollte die Portabilität getestet werden. * Alternativtext sollte den Zweck des Bildes vermitteln, ohne die benachbarte Bildunterschrift zu wiederholen. Status-Badges können statt ausführlicher Dateinamen prägnante Beschriftungen wie „Build: passing“ verwenden. * Badges sind remote generierte Bilder, deren Verfügbarkeit, Caching, Datenschutz und Korrektheit von einem anderen Dienst abhängen. Daher eignen sie sich nicht für wesentliche Projektinformationen. * Im Repository gehostete Bilder werden zusammen mit dem Projekt versioniert. Links zu einem Branch können sich jedoch ändern, während Links zu einem Commit unveränderlich, aber schwieriger zu pflegen sind. * Große Screenshots verlangsamen Repository-Seiten und Klonvorgänge, wenn sie direkt committet werden. Berücksichtigen Sie daher Abmessungen, Komprimierung, Aktualisierungshäufigkeit und Speicherort. * Dunkle und helle GitHub-Farbschemata können transparente Logos oder Diagramme unlesbar machen. Wo unterstützt, können Media Queries für Bildquellen Grafiken passend zum jeweiligen Farbschema bereitstellen. ## Ein praxisnaher Ansatz 1. 1\ Legen Sie Eigentümerschaft und Lebensdauer des Assets fest, bevor Sie die Markdown-URL auswählen. 2. 2\ Passen Sie Screenshots an eine gut lesbare Breite an und optimieren Sie sie, ohne den Text unscharf zu machen. 3. 3\ Verfassen Sie einen prägnanten Alternativtext und verwenden Sie einen aussagekräftigen Dateinamen. 4. 4\ Sehen Sie sich das README im GitHub-Renderer in der Vorschau an und überprüfen Sie die Links aus Forks und Paketspiegeln. Ein vierstufiger Medienworkflow ## Architekturgrenze GitHub steuert das Rendering von READMEs und die Repository-Berechtigungen. Bildverarbeitungstools können Dateien vorbereiten, bevor sie committet oder verlinkt werden. Sie laden sie jedoch weder in den Git-Verlauf hoch noch verwalten sie GitHub-Anhänge. ## Häufig gestellte Fragen ### Sollten README-Bilder relative oder absolute URLs verwenden? Verwenden Sie für Dateien, die zusammen mit dem Repository versioniert werden, relative Pfade, da sie normalerweise Branches und Forks folgen. Verwenden Sie eine absolute HTTPS-URL, wenn das Asset ausdrücklich einem anderen System zugeordnet ist. Testen Sie jede Form in jedem wichtigen Renderer, da Paket-Websites und kopiertes Markdown Pfade unterschiedlich auflösen können. ### Lässt sich die Größe eines README-Bildes mit Markdown ändern? Einfaches Markdown bietet keine portable Syntax für Größenangaben. Verwenden Sie ein einfaches HTML-Element `img` mit `width` und `height`, wenn eine Größenangabe erforderlich ist, und zeigen Sie anschließend eine Vorschau auf GitHub an. Optimieren Sie auch die Quelldatei, da die Anzeigemaße die Anzahl der heruntergeladenen Bytes nicht verringern. ### Ist das Einbetten eines Bildes als Base64 eine gute Möglichkeit, defekte Links zu vermeiden? In der Regel nicht. Base64 erschwert das Lesen und Prüfen des READMEs, vergrößert dessen Textumfang, schränkt die Flexibilität beim Caching ein und wird möglicherweise von einigen Renderern abgelehnt. Eine versionierte Bilddatei oder eine bewusst verwaltete öffentliche URL lässt sich leichter pflegen. ### Sind extern gehostete README-Bilder für private Repositorys sicher? Gehen Sie nicht davon aus. GitHub ruft gerenderte Bilder über seinen anonymisierenden Proxy ab und speichert sie im Cache. Daher werden Bilder, die Cookies oder ein privates Netzwerk benötigen, nicht angezeigt. Andere Renderer ermöglichen Lesern möglicherweise den direkten Kontakt mit dem Host, und eine öffentliche URL kann ein Asset unabhängig von den Repository-Berechtigungen zugänglich machen. Vermeiden Sie vertrauliche Inhalte, verwenden Sie einen genehmigten Host und informieren Sie sich über die aktuelle Bildverarbeitung von GitHub, bevor Sie Ressourcen von Drittanbietern einbetten. ### Wie sollten Screenshots mit Kontodaten behandelt werden? Erstellen Sie die Aufnahme nach Möglichkeit mit einem eigenen Testkonto. Schneiden Sie irrelevante Bereiche zu, schwärzen Sie Tokens und personenbezogene Daten, prüfen Sie Benachrichtigungen und die Browseroberfläche und entfernen Sie sensible Metadaten. Decken Sie sensible Texte mit undurchsichtigen Flächen ab, statt sie weichzuzeichnen oder zu verpixeln. Verdeckte Zeichen lassen sich manchmal aus den veröffentlichten Pixeln rekonstruieren, und zugrunde liegende Details können zudem in Quelldateien oder im Bearbeitungsverlauf erhalten bleiben. Medienperformance ## Mit verwandten Leitfäden fortfahren * [Fünf bewährte Verfahren für HTML- und CSS-Hintergrundbilder](/de/guides/html-background-image-best-practices.md)\ Fünf bewährte Verfahren für CSS-Hintergrundbilder, die Komposition, Barrierefreiheit und Seitenleistung ausgewogen berücksichtigen. * [React-Bilder: fünf Wege vom statischen Import zum Nutzer-Upload](/de/guides/import-images-in-react.md)\ Vergleichen Sie statische Importe, öffentliche Pfade, externe URLs, CSS-Importe und Ergebnisse von Laufzeit-Uploads in React. * [Sechs zuverlässige Wege, Bilder in Python zu speichern](/de/guides/save-images-in-python.md)\ Bilder aus Bytes, URLs, Pillow, OpenCV, Uploads und verwalteten Verarbeitungsergebnissen speichern, ohne die Fehlerbehandlung zu beeinträchtigen. * [Acht Verfahren zur Bild-SEO-Optimierung](/de/guides/image-seo-optimization.md)\ Acht Bild-SEO-Verfahren für Semantik, Abmessungen, Formate, Leistung, Auffindbarkeit und Erfolgsmessung. * [Responsive Bilder über eine einzige URL ausliefern](/de/guides/serve-responsive-images-from-one-url.md)\ Leiten Sie jede Bildgröße aus einer kanonischen URL ab, cachen Sie die Ergebnisse am Edge und halten Sie die Encoding-Kosten trotz wachsendem Traffic stabil.