Wie man Readme-Dateien bei GitHub und Co formatiert.
Was ist eigentlich der Unterschied zwischen einer Readme-Datei und einer Readme.md-Datei? Und wie formatiert man eine Readme-Datei, damit sie übersichtlich ist und beispielsweise bei GitHub geparst und dargestellt wird? Das erfährst Du hier >>
Markdown ist ein beliebtes Tool, welches Text in HTML konvertiert. Es wurde entwickelt, um Autoren die Arbeit zu erleichtern, verständliche Texte zügig zu schreiben und anschließend in HTML umzuwandeln.
Aber wieso gibt es Readme- und Readme.md-Dateien? Die Lösung ist ganz einfach: Während es für “normale” Readme-Dateien keine Konvention gibt, enthalten Readme.md-Dateien mittels Markdown strukturierten Inhalt, der dann beispielsweise bei GitHub direkt zu einer beschreibenden HTML-Seite umgewandelt wird.
Markdown zur Erstellung von README-Dateien
Markdown wird heute von vielen verschiedenen Gruppen verwendet, darunter auch Entwickler, die ihre Projekte auf Plattformen wie Github veröffentlichen. Github bietet seinen Usern an, README-Dateien bequem mit Markdown zu formatieren. Nachfolgend erhältst Du einen Überblick über die wichtigsten Syntaxen zur Formatierung Deiner Texte und README-Dateien.
Grundkenntnisse zur Formatierung
Markdown besteht aus leicht zu lernenden Syntaxen, die das rapide Formatieren eines Textes erlauben. Diese werden im Anschluss erläutert:
Überschriften
Die Erstellung mit Überschriften, welche in HTML mit dem h-tag formatiert werden, erfolgt mit dem Rautezeichen (#). Überschriften kannst Du von h1 bis h6 formatieren:
# Die erste Überschrift ## Noch eine Überschrift ### Abschließend eine weitere ÜberschriftTextformatierung
Zur Formatierung von Text verwenden Autoren verschiedene Stile, insbesondere Fett- und Kursivschrift:
Formatierung Markdown-Syntax Beispiel Fett ** ** oder __ __ **Fetter Text** Kursiv * * oder _ _ *Kursiver Text*Zitate
Zitate werden mit dem Symbol größer als (>) begonnen:
> Ich bin ein Zitat!Für Zitate innerhalb eines Satzes wird ein einzelnes, rückwärts geneigtes Hochkomma verwendet:
In diesem Satz möchte ich `ein Zitat` darstellen.Links
Die Erstellung von Inline-Links erfolgt über eckige Klammern ([]) für den Linktext gefolgt von runden Klammern (()) für die URL:
Für weitere Informationen [hier](http://domain.de) klicken.Bilder
Das Einbinden von Grafiken ähnelt der Integrierung von Links. Bilder beginnen mit einem Ausrufezeichen (!):
Listen
Listen werden geordnet oder ungeordnet mit einem Bindestrich (-) oder einer Zahl (1.) begonnen.
Ungeordnet:
- ungeordneter Listenpunkt 1 - ungeordneter Listenpunkt 2 - ungeordneter Listenpunkt 3Geordnet:
1. geordneter Listenpunkt 1 2. geordneter Listenpunkt 2 3. geordneter Listenpunkt 3Beide Stile können miteinander kombiniert werden:
1. Titel 1 - Punkt 1 - Punkt 2 2. Titel 2 - Punkt 1 - Punkt 2Erweiterte Syntaxen für formschöne Texte
Die zuvor genannten Syntaxen wurden von dem Erfinder von Markdown, John Gruber, definiert. Sein Markdown-Prozessor wurde inzwischen um weitere Syntaxen erweitert, GitHub Flavored und MultiMarkdown, die neue Formatierungen ermöglichen.
Tabellen
Tabellen sind wunderbar dazu geeignet, um bestimmte Informationen übersichtlich darzustellen. Sie werden mit Pipes (|) und Bindestrichen (-) formatiert:
| Linke Überschrift | Rechte Überschrift | | ------------------ | ------------------ | | Etwas Text hier | Ein bisschen hier |Mit Doppelpunkten (:) kannst Du die Textausrichtung bestimmen:
| Überschrift 1 | Überschrift 2 | Überschrift 3 | |:--------------|:-------------:|--------------:| | Links | Zentriert | Rechts |Innerhalb von Tabellen kannst Du natürlich andere Syntaxen verwenden, um Deinen Text zu stylen (Fett- und Kursivschrift zum Beispiel).
Fußnoten
Mit Fußnoten hast Du die Möglichkeit, dem Leser Informationen zu geben, ohne den Lesefluss zu stören. Fußnoten sind kleine, hochgestellte Nummerierungen, die hinter einem Wort erscheinen und zum Ende des Dokuments verlinken.
Hier ist ein Text, der weitere Informationen[^fu1] voraussetzt.Die erste Syntax kreiert die Verlinkung. Nun musst Du Ihr einen entsprechenden Text zuweisen, den Du unter der Textpassage oder am Ende des Dokuments definierst:
[^fu1]: Weitere Informationen hierIn Fußnoten kannst Du Links einbauen und Text formatieren.
HTML-Tags in Markdown
Markdown ist letztendlich ein Tool, um Text zu praktischem HTML zu konvertieren. Aus diesem Grund ist es möglich, HTML-Tags in Markdown-Dokumenten zu verwenden.
Grundsätzlich kannst Du also alle möglichen HTML-Tags in Deine Markdown-Dokumente einfügen, die der Markdown-Syntax nicht unterstützt.