Tutorial: Markdown zur Formatierung von README-Dateien

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 Überschrift

Textformatierung

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 (!):

![Bildtext](Linkzumbild.jpg "Bildtitel")

Listen

Listen werden geordnet oder ungeordnet mit einem Bindestrich (-) oder einer Zahl (1.) begonnen.

Ungeordnet:

- ungeordneter Listenpunkt 1
- ungeordneter Listenpunkt 2
- ungeordneter Listenpunkt 3

Geordnet:

1. geordneter Listenpunkt 1
2. geordneter Listenpunkt 2
3. geordneter Listenpunkt 3

Beide Stile können miteinander kombiniert werden:

1. Titel 1
- Punkt 1
- Punkt 2
2. Titel 2
- Punkt 1
- Punkt 2

Erweiterte 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 hier

In 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.

Crashkurs in Videoform