Vier Wege für Bilder und Badges in GitHub-READMEs

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.

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.

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.

![Diagram showing the request flow from the browser through the API to object storage](docs/request-flow.png)

<p align="center">
  <img
    src="docs/dashboard.png"
    alt="Dashboard showing three completed uploads"
    width="720"
  />
</p>

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.

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.