Black Friday50 % RABATTZum Angebot
← Zurück zum Blog

README-Beispiele 2026: 10 READMEs zum Nachmachen + Vorlage

Von Morgan•Veröffentlicht 12. November 2026•13 min Lesezeit

Ein gutes README sagt Neulingen in einem Satz, was das Projekt macht, zeigt es in einem Screenshot oder kurzen GIF in Aktion und bringt es mit drei Befehlen zum Laufen. Die README-Beispiele unten, von bat, lazygit, FastAPI und weiteren Projekten, ergänzen Installationsschritte pro Betriebssystem, ein minimales Nutzungsbeispiel und Links zu Mitwirkung, Lizenz und vollständiger Doku.

Diese zehn ergänzen die Starship-Analyse in diesen Beispielen für technische Dokumentation. Die Beispiele 1 bis 8 sind echte READMEs, die du auf GitHub öffnen kannst. Die Beispiele 9 und 10 nutzen erfundene Daten. Profil-READMEs auf GitHub sind ein eigenes Thema.

#ProjektTypWas herausstichtÜbernimm das
1batCLIScreenshot pro FeatureEin Beleg für jede Behauptung
2lazygitTerminal-UIClip pro FeatureTasten neben jedem Clip
3gumCLIGeskriptete GIFsDemos, die du neu aufnehmen kannst
4FastAPIWeb-FrameworkErstellen, ausführen, prüfenDie Ausgabe zeigen
5RuffEntwicklertoolDiagramm für hell und dunkelVisuals, die dem Theme folgen
6PowerToysDesktop-AppAufklappbare InstallationenEin kurzer Installationsabschnitt
7SupabasePlattformArchitekturdiagrammDie Funktionsweise als Zeichnung
8ReactUI-BibliothekREADME als WegweiserAuf die Doku-Website verlinken
9invoice-sync (ausgearbeitetes Beispiel)Interner ServiceOwner und RufbereitschaftSichtbare Zuständigkeit
10Baumerhebung (ausgearbeitetes Beispiel)DatensatzVariablen mit EinheitenReiner Text

Was eine gute README-Datei enthält (Checkliste der Abschnitte)

Laut GitHub Docs sollte ein README abdecken, was das Projekt macht, warum es nützlich ist, wie der Einstieg gelingt, wo es Hilfe gibt und wer es pflegt.

README.md und README.rst werden auf GitHub und GitLab formatiert dargestellt. README.txt bleibt reiner Text, was gut zu Datensätzen passt. GitHub sucht zuerst in .github, dann im Stammverzeichnis und dann in docs, kürzt alles über 500 KiB und baut aus deinen Überschriften ein Inhaltsverzeichnis. Ein manuelles Inhaltsverzeichnis ist also optional.

Aufbau einer README-Datei: Checkliste der Abschnitte nach Projekttyp

AbschnittBibliothekCLIAppInterner ServiceDatensatz
Name + Beschreibung in einem SatzPflichtPflichtPflichtPflichtPflicht
Hero-Screenshot oder GIFOptionalEmpfohlenPflichtOptionalentfällt
BadgesEmpfohlenEmpfohlenOptionalOptionalentfällt
FunktionenEmpfohlenEmpfohlenPflichtOptionalentfällt
VoraussetzungenPflichtEmpfohlenPflichtPflichtOptional
Installation oder SchnellstartPflichtPflichtPflichtPflichtentfällt
Nutzungsbeispiel + AusgabePflichtPflichtEmpfohlenEmpfohlenentfällt
KonfigurationEmpfohlenEmpfohlenOptionalPflichtentfällt
ProjektstrukturOptionalOptionalOptionalEmpfohlenPflicht
Funktionsweise oder MethodenOptionalOptionalOptionalPflichtPflicht
TestsEmpfohlenEmpfohlenOptionalPflichtentfällt
Dateien, Variablen und EinheitenentfälltentfälltentfälltentfälltPflicht
MitwirkenEmpfohlenEmpfohlenEmpfohlenOptionalentfällt
Maintainer oder Owner-TeamOptionalOptionalOptionalPflichtPflicht
LizenzPflichtPflichtPflichtOptionalPflicht
SupportEmpfohlenEmpfohlenPflichtPflichtEmpfohlen
Status oder RoadmapOptionalOptionalOptionalOptionalOptional

Andere Dokus bekommen eigene Dateien: CHANGELOG.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, ARCHITECTURE.md, LICENSE sowie im Ordner .github die Issue-Templates und das Pull-Request-Template.

10 README-Beispiele, die sich zum Nachmachen lohnen

1. bat: ein Screenshot für jedes Feature

bat, ein cat-Klon mit Syntaxhervorhebung, belegt jede Behauptung mit einem Bild.

README-Beispiel: bat mit Logo, Badges, Menü und einem Feature-Screenshot
README-Beispiel: bat mit Logo, Badges, Menü und einem Feature-Screenshot
  1. Ein Logo, das im Repo liegt, mit Alt-Text.
  2. Drei Badges.
  3. Eine Zeile, dann ein Menü.
  4. Ein Screenshot pro Feature.

Nicht nachmachen: Die Screenshots sind per Hotlink von Imgur eingebunden. Der Bild-Proxy von GitHub zeigt sie auf github.com weiterhin an, aber Imgur sperrt seit dem 30. September 2025 den Zugriff aus Großbritannien. Lokale Vorschauen und gespiegelte Dokus zeigen Lesern in Großbritannien deshalb ein kaputtes Bild. Committe Bilder ins Repo.

2. lazygit: ein kurzer Clip pro Feature

lazygit, eine Terminal-Oberfläche für Git, wirbt mit einer witzigen Tirade über den Ärger mit Git und zeigt dann jedes Feature in Bewegung.

lazygit-README: Inhaltsverzeichnis, Feature-Überschrift, Tastenhinweise und Video
lazygit-README: Inhaltsverzeichnis, Feature-Überschrift, Tastenhinweise und Video
  1. Ein Inhaltsverzeichnis.
  2. Eine Überschrift pro Feature.
  3. Die Tasten, die du drückst, in Worten.
  4. Ein kurzes Video, auf GitHub hochgeladen.

Übernimm das: Ein kurzer Clip pro Feature schlägt ein langes GIF.

3. gum: GIFs, die aus Skripten entstehen

gum ergänzt Shell-Skripte um Eingabeabfragen und Spinner. Seine 12 GIFs, erstellt mit VHS, stammen größtenteils aus .tape-Skripten im Repo.

gum-README: Demo-GIF, Link zum Skript und ein GIF pro Befehl
gum-README: Demo-GIF, Link zum Skript und ein GIF pro Befehl
  1. Ein Demo-GIF unter dem Slogan.
  2. Ein Link zu seinem Skript.
  3. Ein Abschnitt pro Befehl.
  4. Ein GIF pro Befehl, mit Alt-Text wie „Shell running gum input typing Not much, you?“

Übernimm das: geskriptete Demos. Ohne eigenes Hosting wie das von Charm committest du das GIF ins Repo.

4. FastAPI: die Ausgabe zeigen, nicht nur den Code

FastAPI, ein Web-Framework für Python, kommt in drei Überschriften vom Code zum Ergebnis.

FastAPI-README: Create it, Run it, Check it und API-Doku
FastAPI-README: Create it, Run it, Check it und API-Doku
  1. Create it: eine vollständige main.py.
  2. Run it: ein Befehl und seine Ausgabe.
  3. Check it: das JSON, das du sehen wirst.
  4. Die API-Doku, die es erzeugt, als Screenshot.

Nicht nachmachen bei kleinen Projekten: der lange Sponsorenblock über dem Beispiel.

5. Ruff: ein Diagramm, das dem Theme folgt

Ruff, ein Linter für Python, stellt die Geschwindigkeit an den Anfang.

Ruff-README: Badges, Links und ein Diagramm für helles und dunkles Theme
Ruff-README: Badges, Links und ein Diagramm für helles und dunkles Theme
  1. Badges für Version, Lizenz und CI.
  2. Links zu Doku und Playground.
  3. Ein Benchmark-Diagramm mit dem Alt-Text „Shows a bar chart with benchmark results.“
  4. Eine dunkle Variante über ein picture-Element, gehostet auf der Upload-Domain von GitHub.

Übernimm das: Charts und Diagramme, die sich dem Theme anpassen.

6. PowerToys: eine große App, trotzdem leicht zu überfliegen

PowerToys bringt über 30 Windows-Hilfsprogramme in einem README unter, das sich leicht überfliegen lässt.

PowerToys-README: Hero-Bild, Links, Tabelle der Tools und Installationsblöcke
PowerToys-README: Hero-Bild, Links, Tabelle der Tools und Installationsblöcke
  1. Helle und dunkle Hero-Bilder über relative Pfade.
  2. Doku, Blog und Release Notes ganz oben.
  3. Eine Tabelle der Tools mit Icons samt Alt-Text.
  4. Vier aufklappbare Installationsblöcke.

Übernimm das: Klapp lange Installationswege ein. Nicht nachmachen: Das Hero-Bild hat kein alt-Attribut.

7. Supabase: die Funktionsweise in einem Diagramm

Das README des Monorepos von Supabase ergänzt einen Screenshot des Dashboards sowie Links zu Doku und Support.

Supabase-README: Logo, Checkliste, How it works und Diagramm
Supabase-README: Logo, Checkliste, How it works und Diagramm
  1. Ein Logo pro Theme.
  2. Eine Feature-Checkliste mit Links zur Doku.
  3. „How it works“ in einfachen Worten.
  4. Ein Architekturdiagramm über einen relativen Pfad.

Hinweis: Das Logo nutzt die älteren Fragmente #gh-light-mode-only und #gh-dark-mode-only. Die GitHub Docs nennen nur picture.

8. React: das README als Wegweiser

React hält sein README kurz und überlässt die Details einer Docs-as-Code-Website.

React-README: Beschreibung, Prinzipien, Links zur Installation und Beispiel
React-README: Beschreibung, Prinzipien, Links zur Installation und Beispiel
  1. Ein Satz dazu, was React ist.
  2. Drei Prinzipien.
  3. Links zu Installation und Doku.
  4. Ein winziges Beispiel und seine Ausgabe.

9. README für einen internen Service (ausgearbeitetes Beispiel)

Diese Art von README liegt in privaten Repos, deshalb bekommst du selten eines zu sehen. Hier ist eines mit erfundenen Daten.

Beispiel für eine README-Datei: ein fiktiver interner Service mit Owner, Diagramm und Runbooks
Beispiel für eine README-Datei: ein fiktiver interner Service mit Owner, Diagramm und Runbooks
  1. Owner-Team, Chat-Kanal und Rufbereitschaft ganz oben.
  2. Der Zweck in einem Satz und ein Diagramm.
  3. Lokal ausführen nur mit den Namen der Umgebungsvariablen. Secrets kommen aus dem Vault.
  4. Deployment, Dashboards und eine Zeile „Runbooks“, die auf das Runbook verweist.

Übernimm das: Lass das README ein Wegweiser bleiben. Die Schritte bei einem Alert gehören ins Runbook.

10. README.txt für einen Datensatz (ausgearbeitetes Beispiel)

Für Forschungsdaten listet der Leitfaden der Cornell University diese Abschnitte auf, und der Leitfaden der Harvard Medical School verlangt ein README als reinen Text pro Datensatz, keine Word-Datei.

TITEL     Erhebung des städtischen Kronendachs
KONTAKT   A. Rivera, data-team@example.org
ZEITRAUM  Erhoben vom 2026-04-02 bis 2026-06-30 (ISO 8601)
LIZENZ    CC BY 4.0
DATEIEN   trees_2026.csv (eine Zeile pro Baum), photos/PLOTID_YYYY-MM-DD.jpg
CODES     NA = nicht gemessen; SPP = Artcode
VARIABLEN
  dbh_cm     Brusthöhendurchmesser in 1,3 m Höhe, Zentimeter
  height_m   Baumhöhe, Meter
METHODEN  Höhen mit einem Laser-Entfernungsmesser gemessen.
ZITATION  Rivera A. (2026). Erhebung des städtischen Kronendachs [Datensatz].

So fügst du Screenshots und GIFs in ein README ein

Was du zeigst

Setz ein einziges Hero-Visual unter die Beschreibung. Schneide eng zu, nutze erfundene Daten, zeig eine Idee pro Bild und gib ihm etwas Rand, damit es in beiden Themes funktioniert. Nummeriere die Einrichtungsschritte einer GUI mit passenden Callouts.

Vorher und nachher: ein README nur mit Text und eines mit Demo-GIF und Schnellstart
Vorher und nachher: ein README nur mit Text und eines mit Demo-GIF und Schnellstart

Demo als GIF oder Video

Beschränk eine Demo auf eine Aufgabe in 5 bis 10 Sekunden, etwa 800 px breit bei 10 bis 15 fps, aufgenommen auf dem Mac oder unter Windows. GitHub erlaubt 10 MB pro Bild oder GIF und 10 MB für Videos (100 MB bei bezahlten Plänen).

Ein MP4 wird nur dann direkt im README abgespielt, wenn du es im Editor von GitHub hochlädst (eine URL unter github.com/user-attachments). Ein video-Tag, das auf eine committete .mp4-Datei zeigt, wird entfernt. Prüf das Ergebnis, während du ausgeloggt bist.

Tools fürs Terminal: asciinema plus agg (wie du eine Terminal-Sitzung aufnimmst) oder VHS. Eingebaute Tools: macOS speichert Bildschirmaufnahmen als .mov-Dateien, die du in ein GIF umwandeln kannst. Das Snipping Tool speichert MP4 und kann bis zu 30 Sekunden als GIF exportieren.

Geskriptetes Demo-GIF der fiktiven CLI driftcheck, die in 7,5 Sekunden abweichende Konfigurationsdateien markiert
Geskriptetes Demo-GIF der fiktiven CLI driftcheck, die in 7,5 Sekunden abweichende Konfigurationsdateien markiert

Bilder im Repo mit relativen Pfaden ablegen

Committe Bilder in docs/images/ oder .github/assets/ und verlinke sie über relative Pfade. So werden sie auf dem aktuellen Branch aufgelöst und überstehen Forks, und ein Pfad mit führendem Schrägstrich beginnt im Stammverzeichnis des Repos. GitHub unterscheidet bei Pfaden zwischen Groß- und Kleinschreibung, auch wenn dein Mac oder PC das nicht tut. Für eine feste Größe nutzt du ein img-Tag:

![driftcheck markiert zwei abweichende Konfigurationsdateien](docs/images/demo.gif)
<img src="docs/images/hero.png" alt="driftcheck-Scanergebnisse in einem Terminal" width="800">

Du kannst eine Datei auch in den Web-Editor von GitHub ziehen. Bilder in privaten Repos sehen nur Leute mit Zugriff.

Helle und dunkle Bilder mit dem picture-Element

Logos, Diagramme und Charts auf transparentem Hintergrund brauchen eine Version für den Dark Mode. GitHub unterstützt das picture-Element (Changelog):

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
  <img src="docs/images/logo-light.svg" alt="driftcheck-Logo" width="320">
</picture>
Ein einfaches img-Logo verschwindet im Dark Mode, ein picture-Element wechselt zu einem hellen Logo
Ein einfaches img-Logo verschwindet im Dark Mode, ein picture-Element wechselt zu einem hellen Logo

Screenshots auf einfarbigem Hintergrund brauchen selten eine. Teste beide Themes in einem öffentlichen Demo-Repo.

Alt-Text und Dateigröße

Sag in weniger als etwa 125 Zeichen, was das Bild zeigt, zum Beispiel „lazygit beim Stagen einer einzelnen Zeile aus einem Diff“ (Alt-Text für Bilder). Nutze ein leeres alt-Attribut nur für dekorative Bilder (Entscheidungsbaum des W3C). Halte Screenshots unter etwa 1 MB und verkleinere schwere GIFs.

Vor dem Commit schwärzen

Die Git-Historie behält jede Version, und Uploads in öffentlichen Repos lassen sich ohne Anmeldung öffnen. Verdeck Tokens, E-Mail-Adressen und Kundendaten mit einem deckenden Kasten, denn Weichzeichnen und Verpixeln lassen sich rückgängig machen (wie du Text schwärzt). Rotiere jedes Secret, das schon committet wurde.

Wenn du die Demo selbst aufnehmen willst: ScreenSnap Pro (Mac und Windows) nimmt direkt als GIF oder als MP4 auf. Das MP4 kannst du im eingebauten Editor kürzen, beschleunigen und mit automatischem Zoom versehen, bevor du MP4 oder GIF exportierst. Für Screenshots setzt sein Bildeditor das Bild mit Rand auf einen von über 500 Hintergründen, nummeriert Schritte mit dem Zähler-Werkzeug und deckt Secrets mit einem gefüllten Rechteck ab.

Diese Werkzeuge gibt es für Screenshots, nicht für Aufnahmen, also nimm Demos mit erfundenen Daten auf. Die Cloud-Links von ScreenSnap Pro taugen für einen schnellen Hinweis in Slack, nicht für Bilder im README.

ScreenSnap Pro
Von den Machern dieser Seite

Genug von langweiligen Screenshots? Probier ScreenSnap Pro.

Schöne Hintergründe, professionelle Anmerkungen, GIF-Aufnahme und sofortiges Teilen in der Cloud, alles in einer App. Einmal 39 $ zahlen, für immer besitzen.

Preis und Funktionen ansehen

README-Vorlage zum Kopieren

Kopier diese Beispiel-README-Datei für die fiktive CLI driftcheck. HTML-Kommentare erklären jeden Teil.

<!-- Optional: ein Logo pro GitHub-Theme -->
<picture>
  <source media="(prefers-color-scheme: dark)" srcset="docs/images/logo-dark.svg">
  <img src="docs/images/logo-light.svg" alt="driftcheck-Logo" width="320">
</picture>

# driftcheck

Markiert Konfigurationsdateien, die von der Version in Git abweichen.

<!-- Bis zu 3 Badges -->
[![CI-Build-Status](https://img.shields.io/github/actions/workflow/status/your-org/driftcheck/ci.yml?label=CI)](../../actions)
[![Lizenz: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

![driftcheck markiert zwei abweichende Konfigurationsdateien](docs/images/demo.gif)

## Funktionen

- Prüft YAML-, JSON- und TOML-Dateien
- Lässt die CI bei Abweichungen fehlschlagen (Exit-Code 1)

## Schnellstart

Erfordert Git 2.30 oder neuer.

    brew install your-org/tap/driftcheck   # macOS
    winget install YourOrg.Driftcheck      # Windows

Andere Plattformen: siehe Releases.

## Nutzung

<!-- Der kleinste Befehl und seine echte Ausgabe -->

    $ driftcheck scan ./config
    ✗ 2 files drifted: app.yaml, db.yaml

## Konfiguration

|Option| Standard| Was sie bewirkt|
|---|---|---|
|--base| origin/main| Branch, mit dem verglichen wird|

## Funktionsweise

Designnotizen: [docs/design.md](docs/design.md)

## Mitwirken

Siehe [CONTRIBUTING.md](CONTRIBUTING.md).

## Support

Eröffne ein Issue mit deinem Betriebssystem und deiner Version.

## Lizenz

MIT. Siehe [LICENSE](LICENSE).
  • Lösch Abschnitte, die nicht passen. Bei einer GUI-App ersetzt du den Abschnitt „Nutzung“ durch 3 bis 5 nummerierte Screenshots.
  • Bring Name, Beschreibung, Visual und Schnellstart auf den ersten Bildschirm. Für Kunden exportierst du ein PDF.
  • Verlinke dein Design-Dokument im Abschnitt „Funktionsweise“. Was hineingehört, zeigt diese Vorlage für ein Software-Design-Dokument.

Der Syntax-Leitfaden von GitHub zeigt, was ein README sonst noch nutzen kann: Codeblöcke mit Sprachangabe, Tabellen, eingeklappte Abschnitte, Mermaid-Diagramme, Badges und Hinweisboxen (Alerts) wie > [!NOTE].

Häufige README-Fehler und wie du sie behebst

FehlerLösung
Bilder werden nicht angezeigtAchte auf Groß- und Kleinschreibung im Pfad, vermeide Raw-Links auf umbenannte Branches, verzichte auf Hotlinking und prüf den Zugriff bei privaten Repos
Ein committetes MP4 zeigt nichtsLade es über den Editor von GitHub hoch
GIF zu schwerNimm es kleiner neu auf, komprimier das GIF oder lade ein MP4 hoch
README abgeschnittenVerschieb lange Abschnitte in die Doku. GitHub kürzt alles über 500 KiB
Terminalausgabe als ScreenshotNutze einen Codeblock und extrahiere den Text aus alten Screenshots
Code als gestaltetes BildNutze einen Codeblock. Code-Bilder passen zu Folien und Social-Media-Posts
Veraltete ScreenshotsBenenne Dateien nach Feature und nimm sie bei jedem Release neu auf
Secrets in Screenshots oder .env-BeispielenNutze deckende Kästen und Platzhalterwerte und rotiere geleakte Schlüssel

Häufig gestellte Fragen

Was sollte ein README enthalten?

Einen Namen, eine Beschreibung in einem Satz, einen Screenshot oder ein GIF, Installationsschritte, ein Nutzungsbeispiel sowie Abschnitte zu Mitwirkung, Support und Lizenz. Bei Studien- und Schulprojekten kommen dazu, wie man das Projekt baut und ausführt, welche Dateien dabei sind und welche Probleme bekannt sind.

Wie erstelle ich eine README-Datei?

Füge beim Anlegen des Repositorys auf GitHub ein README hinzu, oder erstelle README.md in einem beliebigen Texteditor. In VS Code öffnest du die Vorschau mit Befehl+Umschalt+V auf dem Mac oder Strg+Umschalt+V unter Windows.

Ist ein README eine .txt-Datei?

Es kann eine sein. README.md und README.rst werden auf GitHub und GitLab als formatierte Seiten dargestellt, während README.txt reiner Text bleibt. Das passt gut zu Datensätzen und Downloads.

Wie kann ich eine README.md-Datei öffnen?

Eine .md-Datei ist reiner Markdown-Text, also öffnet sie jeder Texteditor. Um die Formatierung zu sehen, öffne sie auf GitHub oder GitLab oder in der Markdown-Vorschau von VS Code.

Ist eine README.md notwendig?

Git verlangt keine, aber Leute beurteilen ein Repo danach. Ohne README zeigt GitHub nur die Dateiliste, und Besucher müssen raten, was das Projekt macht.

Gibt es ein Standardformat für READMEs oder einen README-Generator?

Einen offiziellen Standard gibt es nicht. Die Spezifikation Standard Readme und die Vorlage von makeareadme bieten eine gängige Struktur, und README-Generatoren liefern dir ein Grundgerüst. Behandle generierte Ergebnisse als Entwurf.

So schreibst du ein README, das gelesen wird

Starte mit der Vorlage, ergänze ein Hero-Visual und prüf das README, während du ausgeloggt bist. ScreenSnap Pro für Mac und Windows ist ein einmaliger Kauf für 39 $: 1 Lizenz für 2 Computer (2 Aktivierungen, Mac oder Windows). Zu den Preisen.

Autor
Morgan

Morgan

Indie Developer

Indie developer, founder of ScreenSnap Pro. A decade of shipping consumer Mac apps and developer tools. Read full bio

@m_0_r_g_a_n_