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.

Videos von YouTube werden aus GrĂŒnden des Datenschutzes erst angezeigt, wenn die Entsprechenden Cookies akzeptiert wurden. Bitte akzeptiere statistik, Marketing cookies, um das Video zu sehen.

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

RĂŒckmeldungen