README-Beispiele 2026: 10 READMEs zum Nachmachen + Vorlage
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.
| # | Projekt | Typ | Was heraussticht | Übernimm das |
|---|---|---|---|---|
| 1 | bat | CLI | Screenshot pro Feature | Ein Beleg für jede Behauptung |
| 2 | lazygit | Terminal-UI | Clip pro Feature | Tasten neben jedem Clip |
| 3 | gum | CLI | Geskriptete GIFs | Demos, die du neu aufnehmen kannst |
| 4 | FastAPI | Web-Framework | Erstellen, ausführen, prüfen | Die Ausgabe zeigen |
| 5 | Ruff | Entwicklertool | Diagramm für hell und dunkel | Visuals, die dem Theme folgen |
| 6 | PowerToys | Desktop-App | Aufklappbare Installationen | Ein kurzer Installationsabschnitt |
| 7 | Supabase | Plattform | Architekturdiagramm | Die Funktionsweise als Zeichnung |
| 8 | React | UI-Bibliothek | README als Wegweiser | Auf die Doku-Website verlinken |
| 9 | invoice-sync (ausgearbeitetes Beispiel) | Interner Service | Owner und Rufbereitschaft | Sichtbare Zuständigkeit |
| 10 | Baumerhebung (ausgearbeitetes Beispiel) | Datensatz | Variablen mit Einheiten | Reiner 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
| Abschnitt | Bibliothek | CLI | App | Interner Service | Datensatz |
|---|---|---|---|---|---|
| Name + Beschreibung in einem Satz | Pflicht | Pflicht | Pflicht | Pflicht | Pflicht |
| Hero-Screenshot oder GIF | Optional | Empfohlen | Pflicht | Optional | entfällt |
| Badges | Empfohlen | Empfohlen | Optional | Optional | entfällt |
| Funktionen | Empfohlen | Empfohlen | Pflicht | Optional | entfällt |
| Voraussetzungen | Pflicht | Empfohlen | Pflicht | Pflicht | Optional |
| Installation oder Schnellstart | Pflicht | Pflicht | Pflicht | Pflicht | entfällt |
| Nutzungsbeispiel + Ausgabe | Pflicht | Pflicht | Empfohlen | Empfohlen | entfällt |
| Konfiguration | Empfohlen | Empfohlen | Optional | Pflicht | entfällt |
| Projektstruktur | Optional | Optional | Optional | Empfohlen | Pflicht |
| Funktionsweise oder Methoden | Optional | Optional | Optional | Pflicht | Pflicht |
| Tests | Empfohlen | Empfohlen | Optional | Pflicht | entfällt |
| Dateien, Variablen und Einheiten | entfällt | entfällt | entfällt | entfällt | Pflicht |
| Mitwirken | Empfohlen | Empfohlen | Empfohlen | Optional | entfällt |
| Maintainer oder Owner-Team | Optional | Optional | Optional | Pflicht | Pflicht |
| Lizenz | Pflicht | Pflicht | Pflicht | Optional | Pflicht |
| Support | Empfohlen | Empfohlen | Pflicht | Pflicht | Empfohlen |
| Status oder Roadmap | Optional | Optional | Optional | Optional | Optional |
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.

- Ein Logo, das im Repo liegt, mit Alt-Text.
- Drei Badges.
- Eine Zeile, dann ein Menü.
- 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.

- Ein Inhaltsverzeichnis.
- Eine Überschrift pro Feature.
- Die Tasten, die du drückst, in Worten.
- 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.

- Ein Demo-GIF unter dem Slogan.
- Ein Link zu seinem Skript.
- Ein Abschnitt pro Befehl.
- 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.

- Create it: eine vollständige
main.py. - Run it: ein Befehl und seine Ausgabe.
- Check it: das JSON, das du sehen wirst.
- 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.

- Badges für Version, Lizenz und CI.
- Links zu Doku und Playground.
- Ein Benchmark-Diagramm mit dem Alt-Text „Shows a bar chart with benchmark results.“
- 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.

- Helle und dunkle Hero-Bilder über relative Pfade.
- Doku, Blog und Release Notes ganz oben.
- Eine Tabelle der Tools mit Icons samt Alt-Text.
- 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.

- Ein Logo pro Theme.
- Eine Feature-Checkliste mit Links zur Doku.
- „How it works“ in einfachen Worten.
- 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.

- Ein Satz dazu, was React ist.
- Drei Prinzipien.
- Links zu Installation und Doku.
- 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.

- Owner-Team, Chat-Kanal und Rufbereitschaft ganz oben.
- Der Zweck in einem Satz und ein Diagramm.
- Lokal ausführen nur mit den Namen der Umgebungsvariablen. Secrets kommen aus dem Vault.
- 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.

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.

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:

<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>
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.
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 ansehenREADME-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 -->
[](../../actions)
[](LICENSE)

## 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
| Fehler | Lösung |
|---|---|
| Bilder werden nicht angezeigt | Achte 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 nichts | Lade es über den Editor von GitHub hoch |
| GIF zu schwer | Nimm es kleiner neu auf, komprimier das GIF oder lade ein MP4 hoch |
| README abgeschnitten | Verschieb lange Abschnitte in die Doku. GitHub kürzt alles über 500 KiB |
| Terminalausgabe als Screenshot | Nutze einen Codeblock und extrahiere den Text aus alten Screenshots |
| Code als gestaltetes Bild | Nutze einen Codeblock. Code-Bilder passen zu Folien und Social-Media-Posts |
| Veraltete Screenshots | Benenne Dateien nach Feature und nimm sie bei jedem Release neu auf |
| Secrets in Screenshots oder .env-Beispielen | Nutze 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.
Morgan
Indie DeveloperIndie developer, founder of ScreenSnap Pro. A decade of shipping consumer Mac apps and developer tools. Read full bio
@m_0_r_g_a_n_

