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 Ihre README auf GitHub angezeigt wird, werden alle Inhalte, die über 500 KiB hinausgehen, abgeschnitten.
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.
Links zu Abschnitten in README-Dateien und auf Blob-Seiten
Sie können direkt eine Verknüpfung mit jedem Abschnitt mit einer Überschrift vornehmen. Um den automatisch generierten Anker in einer gerenderten Datei anzuzeigen, zeigen Sie mit der Maus auf die Abschnittsüberschrift, um das -Symbol verfügbar zu machen, und klicken Sie auf das Symbol, um den Anker in Ihrem Browser anzuzeigen.
Ausführlichere Informationen zu Links zu Abschnitten finden Sie unter „Links zu Abschnitten“.
Relative Links und Bildpfade in README-Dateien
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 ../.
Ihr Linktext sollte sich in einer einzelnen Zeile befindet. Das folgende Beispiel funktioniert nicht.
[Contribution
guidelines for this project](docs/CONTRIBUTING.md)
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.