Markdown

Anleitung von Norbert Simon

Inhalt

Markdown ist eine leicht erlernbare Auszeichnungssprache, die von John Gruber und Aaron Swartz entwickelt wurde. Sie ermöglicht ein schnelles Erfassen von einfachem Text, der dann von entsprechenden Werkzeugen beispielsweise in HTML-Code übersetzt wird. Sie basiert in den Grundlagen auf der Hervorhebung von Textteilen in einfachen Text-E-Mails. Mit Outlook und Co. ist diese Form des hervorheben ein wenig in Vergessenheit geraten, denn dort wird mit WYSIWYG1-Editoren dafür gesorgt, dass kursiv oder fett per Formatleiste eingefügt werden können. Früher hat man sich dafür in reinem Text mit Symbolen geholfen, die Textbereiche eingefasst haben oder Absätzen vorangestellt wurden. Genauso macht es Markdown. Streng betrachtet ist Markdown deshalb nichts Neues, sondern etwas vergleichsweise Altes, das zeitgemäß weiterentwickelt wurde.

Wozu das?

Jetzt mag sich die Frage einstellen, warum ich mich mit einfachen Sachen zufrieden geben soll, wenn es doch schon weiterentwickelte Möglichkeiten gibt. Darauf gibt es — je nach Sichtweise — mehrere Antworten.

Und wie?

Vorweg werden die Optionen beschrieben, Beispiele folgen am Ende des jeweiligen Abschnitts.

Die Grundregeln sind bereits in der Einleitung angeklungen, die Elemente für einen schnellen und erfolgreichen Start in die Welt von Markdown werden im nachfolgenden Abschnitt behandelt. Darüber hinaus gibt es einige Erweiterungen, die deutlich komplexere HTML-Resultate ermöglichen. Diesen Ergänzungen, die mal mehr, mal weniger von Markdown-Editoren unterstützt werden, aber nicht zum von Gruber definierten Grundwortschatz gehören, werden hier teilweise ebenfalls vorgestellt.

Ob die Ergänzungen in der jeweils verwendeten Umgebung wie erwartet funktionieren, lässt sich durch ausprobieren am schnellsten herausfinden.

Absatz-Strukturen

Damit sind alle Auszeichnungselemente gemeint, die sich immer auf alles zwischen Anfang und Ende eines Absatzes beziehen. Ein Absatzende ist in Markdown typischerweise durch eine Leerzeile zwischen Texten leicht erkennbar, allerdings ist das nicht zwingend. Technisch gesehen erzeugt die -Taste („Enter-Taste“, „Wagenrücklauftaste“, „Zeilenumbruchtaste“) das Steuerzeichen, mit dem ein Absatzende markiert ist. Wenn wir uns einen Text vom Anfang bis zum Ende ansehen, werden Absätze also immer mit voneinander getrennt, wobei der erste Absatz am Anfang und der letzte Absatz am Ende kein Steuerzeichen hat.

Überschriften

Es gibt sechs Hierarchien, die mit einem # bis sechs ###### Hash-Symbolen („Gartenzaun“, „Gitter-Symbol“) am Zeilenanfang markiert werden.

Zitate

Wenn ein > („größer“)-Zeichen am Absatzanfang steht, wird daraus ein Zitat. Zitate lassen sich auch schachteln, ähnlich wie das E-Mail-Programme tun.

Im HTML-Code wird der mit dem >-Zeichen markierte Bereich typischerweise mit <Blockquote> umschlossen.

Listen

Mit der TAB-Taste, genauer mit Einrückungen, d.h. mit Leerstellen erzeugte Ebenen, können die nachfolgend beschriebenen Listenvarianten eingerückt werden. So lassen sich Hierarchien erzeugen. Abhängig vom „Übersetzer“ des Markdown werden statt Tab-Zeichen mehrere Leerzeichen am Absatzanfang erwartet, typischerweise mindestens 2, damit ein Einzug markiert wird. Je mehr, desto tiefer wird eingezogen.

Fehlt nach dem Tab ein Listensymbol, wird einfach nur ein auf die darüber liegende Ebene eingezogener Absatz erzeugt. Die Listenmarken können gemischt werden, innerhalb der aktuellen Ebene entscheidet das erste Element über die Darstellung.

Ungeordnete Listen

Mit einem - oder einem + am Zeilenanfang wird eine ungeordnete Liste erzeugt.

Geordnete Listen

Hier wird mit einer Zahl 1 (oder jeder anderen) mit einem Punkt und einem Leerzeichen eine nummerierte Liste erzeugt. Um das Zählen muss man sich nicht kümmern, das erledigt der Interpreter. Es kann also einfach immer eine 1 verwendet werden.

Definitionslisten2

Das sind Listen mit einer Überschrift und anschließender Erläuterung. Sie werden an einem Doppelpunkt am Anfang des erklärenden Absatzes erkannt, also nach einem Absatz, der dann als Überschrift interpretiert wird. Die Erläuterungen können direkt nach der Überschrift erfolgen, oder auch mit einer (oder mehreren) Leerzeilen abgetrennt werden. Es dürfen sogar mehrere Absätze unter einer Überschrift stehen, allerdings darf nur vor dem ersten Absatz der Doppelpunkt stehen.

Tabellen3

Ein durch PHP-Markdown-Extra bekannt gemachtes Verfahren wird von vielen Interpretern unterstützt. Spalten werden mit dem Pipe-Symbol | voneinander getrennt. Am Zeilenanfang und -ende ist das Zeichen optional, allerdings muss man sich entscheiden, hier kann man nicht mal so, mal so formatieren.

Tabellen werden an der Titelzeile erkannt, der eine Formatzeile folgt. Die Titelzeile ist maßgeblich für die Interpretation der Auszeichnungen (Pipe-Symbol am Anfang/Ende). In der Formatzeile wird die Ausrichtung des Textes in der Spalte definiert, manche Interpreter unterstützen sogar Mehrfachspalten.

Codebeispiele

Mit drei oder mehr Tilde-Symbolen (~~~) am Zeilenanfang können Bereiche eingefasst werden, die wie eingegeben im HTML-Dokument angezeigt werden. Damit das sicher erkannt wird, ist eine Leerzeile davor (am Blockanfang) und dahinter (am Blockende) zweckmäßig. Das wird auch als Fenced Codeblock bezeichnet.

Der Bereich wird im HTML typischerweise mit <pre><code> umschlossen.

Horizontale Linen

Trennlinen können mit drei oder mehr alleinstehenden Sternchen *** in einer Zeile erzeugt werden.

Beispiele Absatzformatierung

Aus


# Überschrift 1
bis
###### Überschrift 6

> Das ist ein Kommentar,...

>> und das ein Kommentar im Kommentar

>>> und das ein Kommentar im Kommentar im Kommentar

1. Geordnete Liste
  7. Mit Hierarchie
  1. Weitergezählt
     7. und noch tiefer
     1. Zählt natürlich ebenfalls
1. Und obere Hierarchie weitergezählt
   - mit ungeordneter Liste
   + einfach so
   * Symbole können sogar gemischt werden
9. Welche Nummer am Anfang steht ist egal, wichtig ist nur, dass es eine Zahl, ein Punkt und ein Leerzeichen ist.

wird


Überschrift 1

bis

Überschrift 6

Das ist ein Kommentar,...

und das ein Kommentar im Kommentar4

und das ein Kommentar im Kommentar im Kommentar

  1. Geordnete Liste
    1. Mit Hierarchie
    2. Weitergezählt
      1. und noch tiefer
      2. Zählt natürlich ebenfalls
  2. Und obere Hierarchie weitergezählt
    • mit ungeordneter Liste
    • einfach so
    • Symbole können sogar gemischt werden
  3. Welche Nummer am Anfang steht ist egal, wichtig ist nur, dass es eine Zahl, ein Punkt und ein Leerzeichen ist.

Je nach Stil werden Listen unterschiedlich dargestellt. Hier muss beim Export ggf. mit einer entsprechenden Stilvorlage nachgebessert werden.

Aus

Die Definition
: Das dazugehörende Textelement

  Noch eine Definition

  : Das eingerückte Textelement mit niedrigerer Hierarchie

    Und ein weiterer Absatz unterhalb der Definition.

wird


Die Definition

Das dazugehörende Textelement

Noch eine Definition

Das eingerückte Textelement mit niedrigerer Hierarchie

Und ein weiterer Absatz unterhalb der Definition.


Mit Leerzeilen zwischen Definition und Textelement lässt sich steuern, ob das Textelement mit HTML-Absatzmarken (<P>…</P>) umschlossen wird.

Aus

| Spalte 1 | Spalte 2 | Spalte 3 | Spalte 4 |
| :-: | :- | -: | - |
| Zentriert | Linksbündig | Rechtsbündig | Standard |
|Mehrfachspalten werden allerdings nicht unterstützt|

wird

Spalte 1 Spalte 2 Spalte 3 Spalte 4
Zentriert Linksbündig Rechtsbündig Standard
Mehrfachspalten werden allerdings nicht unterstützt

Beispiele werden mit drei oder mehr Tilde-Symbolen am Anfang einer Zeile erzeugt. Aus

~~~
Beispiel
~~~

wird

Beispiel

Alternativ kann durch mindestens drei Leerzeichen am Zeilenanfang ein Codebereich angelegt werden. Die Leerzeichen müssen allerdings vor jeder Zeile eingefügt werden, bei mehreren Zeilen ist das womöglich etwas anstrengend.

In Common Mark werden statt der Tilde (~) drei `-Zeichen verwendet, das gleiche, wie es auch für Code in fließenden Text verwendet wird (weiter unten beschrieben).

Linien werden mit mindestens drei Sternchen gezogen. Aus

***

wird


Element-Auszeichnung

Die Grundelemente von Standard-Markdown im Absatz sind fett, kursiv, fett & kursiv und als Code. Weitere sind individuell möglich.

Für Zeilenumbrüche in Absätzen ohne darauffolgenden Absatzabstand werden ein paar Leerzeichen an das Ende einer Zeile angehängt und erst dann die -Taste gedrückt. Ohne die Leerzeichen am Zeilenende werden Zeilen im Editor ohne Leerzeile dazwischen wie ein Absatz ohne Umbruch behandelt (wie hier). Mit einem harten Absatzumbruch (aufgrund der Leerzeichen) wird ein Zeilenumbruch mit dem normalen Zeilenabstand erzeugt. Richtige Absätze haben einen etwas größeren Abstand als Zeilen voneinander.

Im HTML-Code wird ein <br> für den Zeilenumbruch eingefügt.

Für Hyperlinks gibt es mehrere Möglichkeiten.

[Text](Adresse "Titel")

Der in rechteckigen Klammern gesetzte Text wird mit der in geschwungenen Klammern enthaltenen Adresse verknüpft. Der (optionale) in Anführungsstrichen gesetzte Titel wird in modernen Browsern als Popup-Text angezeigt.

[Text][Referenz][Referenz]: Adresse "Titel"

Der in rechteckigen Klammern gesetzte Text wird mit einer Referenz verknüpft. Die Adresse (mit optionalem Titel) dazu kann irgendwo im Doument stehen. In einem Dokument können mehrfach referenzierte Links auf die gleiche Referenz verweisen.

Die Referenz ist nur verknüpfendes Element, sie taucht in der HTML-Datei nicht auf.

Text[^Fußnote][^Fußnote]: Anmerkung

Mit dem Caret wird eine besondere Form der Referenz erzeugt. Damit wird am Ende des HTML-Dokuments eine Fußnote mit Rücksprungmarke eingefügt. Die Fußnote selbst kann an beliebiger Stelle im Dokument stehen. Im HTML-Dokument werden die Fußnoten mit einer horizontalen Linie vom Haupttext abgetrennt. Die Fußnote selbst kann auch einen Hyperlink enthalten (siehe Fußnote zu WYSIWYG5).

Es ist relativ egal was als Sprungmarke verwendet, wird, es muss nur eindeutig sein. Die Fußnoten werden — wenn sie unterstützt werden — automatisch aufsteigend durchnummeriert.

Bilder

Bilder sind aufgebaut wie ein direkter Link. Dass der Link kein Sprung, sondern die Einbettung eines Bildes ist, wird durch ein vorangestellten Ausrufezeichen angezeigt.

![Ersatztext](Bildadresse "Titel")

Bilder werden in Originalgröße eingebunden, Skalierung ist auf diesem Weg nicht möglich. Das lässt sich jedoch ggf. über eine entsprechende Stilvorlage realisieren.

„Normales“ HTML

In Markdown-Dateien kann behelfsweise mit HTML-Befehlen gearbeitet werden, wenn das Ziel eine HTML-Übersetzung sein soll. Entsprechende Auszeichnungsbefehle werden von den Interpretern meistens wie Text durchgereicht. Der Browser (und auch die Vorschau) interpretieren dann die HTML-Steuerbefehle. Allerdings muss darauf geachtet werden, dass sich valides HTML ergibt, eine öffnende Sequenz muss eine schließende haben, andernfalls kann das eigenwillige Effekte auslösen.

Wenn es primär darum geht, dass Markdown als HTML-Erzeuger eingesetzt werden soll, ist das Integrieren von HTML-Code unproblematisch. Wenn es primär auf eine sichere Austauschbarkeit von Inhalten ankommt, sollte von dieser Methode nur im Notfall Gebrauch gemacht werden.

Beispiele für Element-Auszeichnung

**fett**fett oder __fett__fett

*kursiv*kursiv oder _kursiv_kursiv

***fett & kursiv***fett & kursiv oder ___fett & kursiv___fett & kursiv

`als Code` ⇒ als Code

<span style="font-size:2em">HTML-Code</span>HTML-Code

Erweiterte Auszeichnung

Es gibt verschiedene Ansätze zur Erweiterung von Markdown. Einige davon werden beispielsweise von Pandoc, einem hocheffizienten Format-Konverter unterstützt. Allerdings müssen sie dort explizit aktiviert werden und — das größte Manko — sie werden lange nicht von jedem Interpreter unterstützt. Von Yellow (dem zugrundeliegenden CMS dieser Seite) aktuell ebenfalls nicht (weshalb dran steht, was heraus kommen soll, bzw. bei entsprechend aktivertem Pandoc heraus kommt):

Weiterführende Quellen

Markdown - Das Original

Pagedown-Extra, Github-Formatierung

Markdown-Extra


  1. WYSIWIG: What you see is what you get ↩︎

  2. Definitionslisten werden nicht von allen Markdown Interpretern vollständig unterstützt. ↩︎

  3. Tabellen werden nicht oder z.T. nur eingeschränkt von Markdown Interpretern unterstützt. ↩︎

  4. Die Darstellung hier ist durch seitenspezfisches CSS stark abweichend. Typischerweise werden Kommentare in Kommentaren weiter eingerückt. Ich verwende die Verschachtelung auf diesen Seiten zur bequemen Markierung mit verschiedenen Farben. ↩︎

  5. Die Fußnote zu WYSIWYG enthält einen Hyperlink zu Wikipedia. Fußnoten werden nur teilweise und variierend in der Darstellung von den Interpretern unterstützt. ↩︎