Skip to main content

Informationen zu README-Dateien

Du kannst eine README-Datei zu Deinem Repository hinzufügen, um anderen Personen mitzuteilen, warum Dein Projekt nützlich ist, was sie mit Deinem Projekt machen können und wie sie es nutzen können.

Informationen zu README-Dateien

Du kannst einem Repository eine README-Datei hinzufügen, um wichtige Informationen zu Deinem Projekt zu kommunizieren. Eine README-Datei in Verbindung mit einer Repositorylizenz, Zitatdatei, Beitragsrichtlinien und Verhaltensregeln kommuniziert Erwartungen an Dein Projekt und unterstützt Dich bei der Verwaltung von Beiträgen.

Weitere Informationen zum Bereitstellen von Richtlinien für dein Projekt findest du unter Einen Verhaltenskodex zu Deinem Projekt hinzufügen und Projekt für sinnvolle Beiträge einrichten.

Die README-Datei ist oft das erste Element, das ein Benutzer beim Besuch Deines Repositorys sieht. README-Dateien enthalten in der Regel folgende Informationen:

  • Was ist die Aufgabe des Projekts?
  • Warum ist das Projekt sinnvoll?
  • Wie können Benutzer am Projekt mitwirken?
  • Wo erhalten Benutzer Hilfe zu deinem Projekt?
  • Wer verwaltet das Projekt und trägt dazu bei?

Wenn Du Deine README-Datei im ausgeblendeten .github, im Stamm oder im docs-Verzeichnis Deines Repositorys ablegst, erkennt GitHub Deine README-Datei und stellt sie automatisch den Besuchern des Repositorys zur Verfügung.

Enthält ein Repository mehrere README-Dateien, wird die angezeigte Datei aus Speicherorten in der folgenden Reihenfolge ausgewählt: das .github-Verzeichnis, dann das Stammverzeichnis des Repositorys und schließlich das docs-Verzeichnis.

Wenn du dem Stammverzeichnis eines öffentlichen Repositorys eine README hinzufügst, deren Namen identisch mit deinem Benutzernamen ist, wird diese automatisch auf deiner Profilseite angezeigt. Du kannst die README deines Profils mit GitHub Flavored Markdown bearbeiten, um einen personalisierten Abschnitt in deinem Profil zu erstellen. Weitere Informationen findest du unter Verwalten der Profil-README.

Automatisch generiertes Inhaltsverzeichnis für README-Dateien

Für die gerenderte Ansicht einer Markdown-Datei in einem Repository einschließlich README-Dateien generiert GitHub automatisch ein Inhaltsverzeichnis basierend auf Abschnittsüberschriften. Du kannst das Inhaltsverzeichnis für eine README-Datei anzeigen, indem Du oben links auf der gerenderten Seite auf das Menüsymbol klickst.

Screenshot der README-Datei für ein Repository. In der oberen linken Ecke wird ein Dropdownmenü mit einem Listensymbol erweitert, um ein Inhaltsverzeichnis anzuzeigen.

Du kannst direkt zu einem Abschnitt in einer gerenderten Datei verweisen, indem Du den Mauszeiger über den Abschnittstitel bewegst, um verfügbar zu machen.

Screenshot einer Infodatei für ein Repository. Links neben einer Abschnittsüberschrift ist ein Linksymbol dunkelorange umrandet.

Du kannst relative Links und Bildpfade in deinen gerenderten Dateien definieren, um Leser dabei zu unterstützen, in deinem Repository zu anderen Dateien zu navigieren.

Ein relativer Link ist ein Verknüpfung, die relativ zur aktuellen Datei ist. Wenn sich beispielsweise eine README-Datei im Root deines Repositorys und eine andere Datei in docs/CONTRIBUTING.md befindet, sieht der relative Link zu CONTRIBUTING.md in deiner README-Datei wie folgt aus:

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

GitHub wandelt deinen relativen Link oder den Bildpfad automatisch anhand dessen um, auf welchem Branch du dich gerade befindest, damit der Link oder der Pfad immer funktioniert. Der Pfad des Links ist relativ zur aktuellen Datei. Links, die mit / beginnen, sind relativ zum Repositorystamm. Du kannst alle relativen Linkoperanden verwenden, z. B. ./ und ../.

Relative Links sind für Benutzer, die dein Repository klonen, einfacher zu verwenden. Absolute Links funktionieren möglicherweise nicht in Klons deines Repositorys - wir empfehlen relative Links zu verwenden, um auf andere Dateien in deinem Repository zu verweisen.

Wikis

Eine README-Datei sollte nur die Informationen enthalten, die Entwickler für ihre ersten Schritte benötigen und die für ihr Projekt relevant sind. Längere Dokumentationen eignen sich am besten für Wikis. Weitere Informationen findest du unter Informationen zu Wikis.

Weiterführende Themen