Markdown
Anleitung von Norbert Simon
Inhalt
- Absatz-Strukturen
- Beispiele für Absatz-Strukturen
- Element-Auszeichnung
- Beispiele für Element-Auszeichnung
- Erweiterte Auszeichnung
- Weiterführende Quellen
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.
- Wenn ich schreibe, habe ich die Hände auf der Tastatur, also sind die Zeichenketten für die Formatierung in optimaler Reichweite. Ich kann das einfach so mit eintippen. Ich muss nicht zur Maus greifen, ich muss keine Sondertastensequenz auslösen, ich schreibe einfach munter vor mich hin.
- Der erzeugte Text ist Klarschrift, d.h. da sind keine Steuerbefehle enthalten, die beim Import in ein anderes System womöglich Dinge auslösen, die ich nicht haben möchte. Womöglich wird eine Auszeichnung nicht so interpretiert, wie ich mir das wünsche. Aber der Text lässt sich problemlos überall hin übertragen. Die Auszeichnungen können dann ggf. mit Suchen und Ersetzen bei geringem Aufwand in die gewünschte Formatierung überführt werden.
Damit ist ein problemloser Datenaustausch über Betriebssystem- und Programm-Grenzen hinweg möglich. Denn das Textformat ist das älteste überhaupt und wird mit sehr hoher Wahrscheinlichkeit noch funktionieren, wenn es diverse Dialekte, wie es beispielsweise HTML, RTF, XML u.a. sind, in der aktuellen Form womöglich gar nicht mehr gibt. Bemerkenswerterweise basieren die Letztgenannten konzeptionell auf dem Textformat, sie sind lediglich mit Formatbefehlen für die interpretierte Darstellung angereichert.
Und wie?
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.
- Definitionslisten4
-
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.
- Tabellen5
-
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
<em><strong>
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
- Geordnete Liste
- Mit Hierarchie
- Weitergezählt
- und noch tiefer
- Zählt natürlich ebenfalls
- Und obere Hierarchie weitergezählt
- mit ungeordneter Liste
- einfach so
- Symbole können sogar gemischt werden
- Welche Nummer am Anfang steht ist egal, wichtig ist nur, dass es eine Zahl, ein Punkt und ein Leerzeichen ist.
wird
***
<h1>Überschrift 1</h1>
bis
<h6>Überschrift 6</h6>
Das ist ein Kommentar,...
und das ein Kommentar im Kommentar2
und das ein Kommentar im Kommentar im Kommentar
- Geordnete Liste
- Mit Hierarchie
- Weitergezählt
- und noch tiefer
- Zählt natürlich ebenfalls
- Und obere Hierarchie weitergezählt
- mit ungeordneter Liste
- einfach so
- Symbole können sogar gemischt werden
- 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 WYSIWYG3).
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
<strong>fett</strong>
⇒ fett oder <strong>fett</strong>
⇒ fett
<em>kursiv</em>
⇒ kursiv oder <em>kursiv</em>
⇒ kursiv
<em><strong>fett & kursiv</strong></em>
⇒ fett & kursiv oder <em><strong>fett & kursiv</strong></em>
⇒ 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):
- durchgestrichen~ → durchgestrichen →
durchgestrichen - H20 → tiefgestellt → H20
- 2^10^ → hochgestellt → 210
- --- → em-dash →
- --- → en-dash → --
-... → Fortsetzungspunkte → ... (…)
Weiterführende Quellen
Markdown - Das OriginalPagedown-Extra, Github-Formatierung
Markdown-Extra1WYSIWIG: What you see is what you get
2Die 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.
3Die 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.
4Definitionslisten werden nicht von allen Markdown Interpretern vollständig unterstützt.
5Tabellen werden nicht oder z.T. nur eingeschränkt von Markdown Interpretern unterstützt.