README mit Markdown erstellen: Aufbau, Vorlage und HTML-Export

Was in eine gute README gehört

Die README ist die Visitenkarte eines Projekts. Sie ist das Erste, was Besucher auf GitHub sehen, und entscheidet oft darüber, ob jemand das Projekt nutzt oder weiterzieht. Eine durchdachte README beantwortet die naheliegenden Fragen in einer sinnvollen Reihenfolge:

• Was ist das? Ein bis zwei Sätze, die das Projekt klar beschreiben.
• Wie installiere ich es? Konkrete Befehle zum Kopieren.
• Wie benutze ich es? Ein kurzes, lauffähiges Beispiel.
• Wie kann ich mitwirken? Hinweise zu Issues und Pull Requests.
• Unter welcher Lizenz steht es? Damit klar ist, was erlaubt ist.

Wichtig ist die Reihenfolge: Das Versprechen kommt zuerst, technische Details später. Wer ganz oben einen Wartungs-Hinweis oder eine lange Geschichte platziert, verliert Leser, bevor sie verstanden haben, worum es geht.

Wichtige Markdown-Elemente für READMEs

Einige Markdown-Bausteine tauchen in fast jeder guten README auf. Badges sind kleine Statusgrafiken für Version, Lizenz oder Build-Status. Technisch sind es Bilder mit einer URL, die ein Badge erzeugt:

![Lizenz](https://img.shields.io/badge/Lizenz-MIT-green)
![Version](https://img.shields.io/badge/Version-1.0.0-blue)

Code-Blöcke sind unverzichtbar für Befehle und Beispiele. Mit drei Backticks und einer Sprachangabe erhalten Sie zusätzlich Syntaxhervorhebung:

```bash
npm install
npm run dev
```

Ein Inhaltsverzeichnis mit Sprunglinks lohnt sich bei längeren READMEs, und Tabellen eignen sich gut für Konfigurationsoptionen. Wie Tabellen genau aufgebaut sind, steht im Ratgeber Markdown-Tabelle erstellen. Eine kompakte Übersicht aller Zeichen finden Sie im Markdown-Spickzettel.

GitHub Flavored Markdown korrekt nutzen

Auf GitHub rendert nicht der nackte Markdown-Standard, sondern GitHub Flavored Markdown (GFM). Das ist gut zu wissen, denn einige beliebte README-Elemente sind GFM-Erweiterungen:

Mehr zu den Eigenheiten und Grenzen lesen Sie im Ratgeber GitHub Flavored Markdown.

Vorlage zum Kopieren

Diese Vorlage deckt die wichtigsten Abschnitte ab. Kopieren Sie sie, benennen Sie die Datei README.md und passen Sie die Inhalte an Ihr Projekt an:

# Projektname

Kurze Beschreibung in einem Satz, was das Projekt macht.

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

## Inhaltsverzeichnis
- [Installation](#installation)
- [Verwendung](#verwendung)
- [Lizenz](#lizenz)

## Installation
```bash
npm install
```

## Verwendung
```bash
npm run dev
```

Beschreiben Sie hier die wichtigsten Befehle.

## Konfiguration
| Option | Standard | Beschreibung      |
| ------ | -------- | ----------------- |
| port   | 3000     | Lokaler Port      |
| debug  | false    | Ausführliche Logs |

## Mitwirken
Pull Requests sind willkommen. Bitte zuerst ein Issue öffnen.

## Lizenz
MIT

Die Sprunglinks im Inhaltsverzeichnis funktionieren auf GitHub automatisch: Der Anker ergibt sich aus der Überschrift in Kleinbuchstaben, Leerzeichen werden zu Bindestrichen.

README als HTML-Vorschau prüfen

Bevor Sie die README hochladen, lohnt ein Blick auf das gerenderte Ergebnis. Fügen Sie Ihren Markdown-Text in den Markdown-zu-HTML-Konverter ein und Sie sehen sofort, wie Überschriften, Listen, Tabellen und Code-Blöcke aussehen werden. So fallen vergessene Trennzeilen oder kaputte Links auf, bevor sie öffentlich sichtbar sind. Die Vorschau läuft lokal im Browser, ohne Upload und kostenlos.

Häufige Fehler

Ein paar Stolperfallen tauchen immer wieder auf. Code-Blöcke ohne schließende Backticks reißen das halbe Dokument in den Code-Modus. Tabellen ohne Trennzeile erscheinen als Textzeile. Relative Bildpfade brechen, wenn die README an einer anderen Stelle eingebunden wird, hier helfen absolute URLs. Und ein häufiger Punkt: Wer GFM-Elemente wie Aufgabenlisten verwendet, sollte nicht erwarten, dass sie in jeder Umgebung außerhalb von GitHub funktionieren.

Häufige Fragen