Eine gute README.md schreiben

Das Erste, was man in einem GitHub-Projekt sieht, ist die README.md. Eine gute README zeigt in 30 Sekunden, worum es geht, wie man es installiert und wie man es benutzt. Hier findest du die übliche Struktur, das wichtigste Markdown und eine Vorlage zum Kopieren.

Zum Mitschreiben öffnest du den Online Markdown-Editor: links schreiben, rechts das Ergebnis sehen.

Was gehört in eine README?

Eine solide README enthält meist in dieser Reihenfolge:

  1. Projektname und ein Satz Beschreibung – welches Problem es löst.
  2. Screenshot oder Demo – ein Bild sagt mehr als Absätze.
  3. Funktionen – drei bis sechs Kernpunkte.
  4. Installation – Befehle zum Kopieren und Ausführen.
  5. Verwendung – das einfachste funktionierende Beispiel.
  6. Konfiguration – Umgebungsvariablen oder Konfigurationsdateien, falls vorhanden.
  7. Mitwirken – wie man Fehler meldet und Änderungen einreicht.
  8. Lizenz – zum Beispiel MIT oder Apache-2.0.

Für kleine Projekte reichen die Punkte 1, 4, 5 und 8. Ziel ist, dass Erstbesucher das Projekt zum Laufen bringen.

Häufig genutztes Markdown

Titel und Beschreibung

# Moread

> Ein Markdown Viewer ohne Installation, der deine Dateien nie hochlädt.

Nutze nur einen #-Titel und ## für Abschnitte. Die vollständige Syntax steht in der Markdown-Anleitung.

Installationsbefehle in Codeblöcken

```bash
git clone https://github.com/you/project.git
cd project
npm install
```

Mit Sprachangabe (bash, python, javascript) hebt GitHub die Syntax hervor.

Screenshots

![Hauptansicht](docs/screenshot.png)

Lege Bilder in einen Ordner wie docs/ oder assets/ und verweise relativ darauf, dann bleiben sie auch nach dem Verschieben erhalten.

Badges

Viele READMEs beginnen mit Badges für Version, Lizenz oder Build-Status:

![License](https://img.shields.io/badge/license-MIT-green)

Ein paar Badges reichen völlig.

Optionen in Tabellen

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `port` | `3000` | Server-Port |
| `debug` | `false` | Debug-Ausgabe anzeigen |

Mehr Tipps gibt es in der Anleitung zu Markdown-Tabellen.

Architekturdiagramme mit Mermaid

GitHub unterstützt Mermaid, du kannst Diagramme also direkt in die README zeichnen:

flowchart LR
    A[Nutzer] --> B[Frontend] --> C[API] --> D[Datenbank]

Details in der Mermaid-Anleitung.

README-Vorlage zum Kopieren

# Projektname

Ein Satz, welches Problem dieses Projekt löst.

![Screenshot](docs/screenshot.png)

## Funktionen

- Funktion eins
- Funktion zwei
- Funktion drei

## Installation

```bash
npm install your-package
```

## Verwendung

```javascript
import { hello } from 'your-package';
hello('world');
```

## Konfiguration

| Option | Standard | Beschreibung |
| --- | --- | --- |
| `option` | `true` | Was diese Option bewirkt |

## Mitwirken

Issues und Pull Requests sind willkommen.

## Lizenz

MIT

Füge die Vorlage in den Online-Editor ein, trage deine Angaben ein und lade sie mit Strg + S als README.md herunter.

Tipps für eine bessere README

  • „So startest du es“ zuerst – die meisten wollen nur installieren und ausprobieren.
  • Befehle kopierbar halten – keine Erklärungen in die Befehlszeilen mischen.
  • Aktuell halten – ändert sich der Code, ändert sich die README.
  • Inhaltsverzeichnis für lange READMEs ergänzen.
  • Übersetzungen wie README.de.md anbieten und oben verlinken.

Zum Schluss README.md in Moread ziehen und prüfen, ob Überschriften, Tabellen und Diagramme stimmen, bevor du pushst.