¶ Markdown
¶ Einführung
¶ Was ist Markdown
Markdown wurde von John Gruber und Aaron Swartz im Jahr 2004 veröffentlicht, mit den Grundgedanken, so einfach lesbar und schreibbar wie möglich zu sein.
Lesbarkeit ist hierbei das oberste Ziel. Ein Markdown-formatiertes Dokument sollte in seiner Grundform veröffentlicht werden können, ohne den Anschein zu erwecken, es sei mit Tags oder Formatierungsbefehlen versehen (wie es bei HTML der Fall ist).
Eine Liste wird beispielsweise mit einem einfachen Bindestrich - erzeugt, für Überschriften wird die Raute # genutzt.
Markdown kann mit jedem simplen Text-Editor oder mit speziellen Markdown-Editoren erstellt werden. Eine besondere Empfehlung spreche ich hier Obsidian aus.
Mit Hilfe von Programmier-Scripten lässt sich Markdown in die unterschiedlichsten Formate umwandeln, beispielsweise auch in HTML.
Der Vorteil von Markdown wird schnell deutlich, wenn man ein HTML-Dokument mit der entsprechenden Markdown-Syntax vergleicht. Ein einfacher Text mit einer Überschrift, einem Absatz und einer Liste sieht in HTML so aus:
<h1>Eine Überschrift erster Ordnung</h1>
<p>Das ist ein Absatz, in HTML wird ein Absatz mit dem "p"-Tag für "paragraph" umschlossen</p>
<ul>
<li>Eine komplette Liste wird in HTML</li>
<li>als "unordered list" (ul) bezeichnet</li>
<li>und ein einzelnes Listenelement</li>
<li>mit "liste item" (li)</li>
</ul>
Die gleiche Formatierung kann man mit Markdown deutlich einfacher und intuitiver erreichen:
# Das ist eine Überschrift
Ein normaler Absatz wird einfach mit Leerzeilen abgetrennt.
- Und eine Liste wird so ausgezeichnet
- wie man es auch intuitiv machen würde.
Wie man sieht ist Markdown deutlich einfacher, und zwar in dreifacher Hinsicht:
- Markdown ist einfacher zu lernen.
- Markdown ist einfacher zu lesen.
- Markdown ist einfacher zu schreiben.
¶ Beispiele
¶ Beispielüberschrift
Beispieltext
- Eintrag 1
- Eintrag 2
##### Beispielüberschrift
Beispieltext
- Eintrag 1
- Eintrag 2
Die Anzahl der
#bestimmt das Header Level.
Mehr dazu folgt in Syntax.
¶ Syntax
Im Folgenden wird die Syntax von Markdown erklärt.
¶ Übersicht
Markdown kommt mit einem guten Dutzend Zeichen für die Formatierung von Dokumenten aus. Die folgende Referenz-Tabelle ist nicht ganz vollständig, enthält aber die wichtigste Syntax. Die vollständige Beschreibung von Markdown findet man auf der Webseite von John Gruber.
| Format | Markdown |
|---|---|
| Absatz | ¶ ¶Absatz¶ ¶ |
| Weicher Umbruch | ¶ ¶Text··¶ |
| Überschrift erster Ordnung | # Headline |
| Überschrift sechster Ordnung | ###### Headline |
| Kursiver Text | _italic_ |
| Kursiver Text | *italic* |
| Fetter Text | __bold__ |
| Fetter Text | **bold** |
| Liste | - list item |
| Liste | * list item |
| Liste | + list item |
| Aufzählung | 5. ordered list item |
| Link | [link text](https://your-url-here.com) |
| Bild |  |
| Verlinktes Bild | [](https://your-url-here.com) |
| Zitat | > interesting quote |
| Inline-Code | ` inline code here ` |
| Code-Block | ```` ····block code here ```` |
| Horizontaler Strich | --- |
¶ Grundsätze
Zusätzlich zur Markdown-Syntax sollte man ein paar Grundprinzipien kennen. Anders als bei normalen Text-Dokumenten entstehen Absätze oder andere Inhaltsblöcke bei Markdown nur dann, wenn sie durch eine Leerzeile (also zwei Returns) abgetrennt sind. Weniger bekannt ist die Syntax für weiche Umbrüche: Weiche Umbrüche werden durch zwei oder mehr Leerzeichen am Ende eines Absatzes und einem einfachen Return erzeugt:
Das ist ein Normaler Abssatz mit zwei Returns
Und das ist ein Absatz
mit einem weichen Umbruch
Das ist ein normaler Absatz mit zwei Returns¶
¶
Und das ist ein Absatz··¶
mit einem weichen Umbruch (erzeugt ein <br/>-tag)
Ein weiteres Prinzip von Markdown ist der Einzug durch vier Leerzeichen oder durch einen Tab am Beginn einer Zeile. Mit dem Einzug lassen sich beispielsweise Listen mit Unter-Ebenen erstellen:
- List Item
- Another List-Item
- Sub-Item
- Sub-Item
* List Item
* Another List-Item
* Sub-Item
* Sub-Item
Markdown-Elemente können auch kombiniert und ineinander verschachtelt werden. Ein beliebtes und häufig genutztes Beispiel ist das verlinkte Bild:
[](/path/to/linked/website)
[
Auch andere Markdown-Elemente können verschachtelt werden, allerdings dürften viele Autoren von der recht komplexen Syntax bald überfordert sein.
Zudem fehlen bei der ursprünglichen Markdown-Definition zahlreiche gebräuchliche Elemente wie beispielsweise Tabellen.
Daher ist die Verwendung von HTML in einem Markdown-Dokument erlaubt.
Allerdings gibt es auch einige Erweiterungen für Markdown, die diese Lücken weitestgehend schließen.
¶ Markdown-Extra Syntax
Markdown-Extra ist in den meisten Markdown-Bibliotheken zumindest teilweise implementiert und erweitert die Markdown-Syntax um
- Tabellen
- Fußnoten
- Abkürzungen
- Definitionslisten
- Fenced Code-Blöcke
- Attribute wie CSS-Klassen und IDs
¶ Tabellen
Tabellen können bei Markdown-Extra mit Hilfe von Pipes | wie im folgenden Beispiel erstellt werden:
| name | usage |
|-----------|-----------:|
| My Name | For Me |
| name | usage |
|---|---|
| My Name | For Me |
Die Syntax ist zwar recht flexibel (mit dem Doppelpunkt : lässt sich beispielsweise die Text-Ausrichtung bestimmen), aber mit den Pipes lassen sich vor allem größere und komplexe Tabellen kaum noch überblicken oder überarbeiten.
¶ Fußnoten
Fußnoten sind ein weiteres, häufig nachgefragtes Element bei der Erstellung von Dokumenten. Sie können in Markdown-Extra mit einer speziellen Referenz erstellt werden:
Ein Text mit einer Fußnote.[^1]
[^1]: Der Fußnoten-Text kann am Seiten-Ende platziert werden.
Ein Text mit einer Fußnote.[1]
¶ Abkürzungen
Abkürzungen können einmalig definiert werden. Anschließend wird die Abkürzung überall im Text als Title-Attribut angehängt und erscheint als Tool-Tipp bei Mouse-Over.
*[HTML]: Hyper Text Markup Language
*[69]: Noice
Wenn ihr über HTML oder 69 hovert, dann seht ihr den Tooltip von oben.
¶ Definitionslisten
Ebenfalls recht speziell sind Definitionslisten, die bei Markdown-Extra mit Hilfe eines Doppelpunktes erstellt werden:
Banana
: A yellow fruit
: A tasty fruit
- Banana
- A yellow fruit
- A tasty fruit
Zur Visualisierung geschrieben in HTML, da Definitionslisten auf dieser Website nicht unterstützt werden.
¶ Code-Blöcke
Während man bei Markdown jede Zeile eines Code-Blocks einrücken muss, kann man bei Markdown-Extra einen Fenced-Code mit umschließenden Backtipps ohne Einrückung erstellen:
\````
<?php
echo "Hello";
<?php
\````
` <?php echo "Hello"; <?php \
¶ Attribute
Einigen Elementen wie Bildern oder Links kann man über eine geschweifte Klammer auch IDs oder Klassen zuordnen:
{.floatRight}
[Link-Button](https://image.url.de){#id-for-js .style-as-button}
Nach der Definition wären sogar Attribute wie width=100px denkbar oder auch Überschriften mit Links zu einem Anker. Allerdings sind diese Details nicht in allen Bibliotheken implementiert und funktionieren daher nicht zuverlässig.
¶ Inline-HTML
Markdowns Syntax hat eine Bestimmung: Benutzt zu werden um für das Web zu schreiben.
Markdown ist kein Ersatz für HTML, nicht einmal Ansatzweise. Der Umfang der Syntax ist sehr klein und entspricht nur einem geringen Teil aller HTML-Tags. Es ist nicht die Absicht von Markdown, das Einfügen von HTML-Tags zu erleichtern. HTML ist bereits einfach genug. Die Idee hinter Markdown ist es, Text so einfach wie möglich zu lesen, zu schreiben und zu bearbeiten. HTML ist ein Publikations-Format; Markdown ist ein Schreib-Format. Daher berücksichtigt seine Syntax nur Inhalte, die mit purem Text zu vermitteln sind.
Für jede Formatierung, die nicht mit Markdown machbar ist, kann einfach HTML verwendet werden. Es ist nicht nötig, HTML zu markieren um es vom Rest abzugrenzen. Es wird einfach in den Text geschrieben.
Die einzige Beschränkung sind Block-Elemente wie z.B. <div>, <table>, <pre>, <p> und so weiter. Sie müssen vom umgebenden Inhalt durch leere Zeilen getrennt sein, außerdem sollten die Start- und End-Tags nicht mit Leerzeichen oder Tabs eingerückt sein. Markdown ist intelligent genug um keine zusätzlichen (ungewollten) <p>-Tags um HTML-Blöcke zu setzen.
So baut man zum Beispiel eine HTML-Tabelle in einen Markdown-Artikel ein:
Dies ist ein normaler Absatz.
<table>
<tr>
<td></td>
<td>Foo 1</td>
<td>Foo 2</td>
<td>Foo 3</td>
<td>Foo 4</td>
</tr>
<tr>
<td>fOo 1</td>
<td>fOo 1</td>
<td>fOo 2</td>
<td>fOo 3</td>
<td>fOo 4</td>
</tr>
<tr>
<td>foO 1</td>
<td>FoO 1</td>
<td>FoO 2</td>
<td>FoO 3</td>
<td>FoO 4</td>
</tr>
</table>
Dies ist noch ein normaler Absatz.
Visualisiert:
Dies ist ein normaler Absatz.
Foo 1 Foo 2 Foo 3 Foo 4 fOo 1 fOo 1 fOo 2 fOo 3 fOo 4 foO 1 FoO 1 FoO 2 FoO 3 FoO 4 Dies ist noch ein normaler Absatz.
Es ist zu beachten, dass Markdowns Syntax innerhalb von HTML-Blöcken nicht interpretiert wird. Es kann zum Beispiel keine Betonung innerhalb von HTML-Blöcken benutzt werden.
Inline-HTML-Tags wie z.B. <span>, <cite>, oder <del> können überall in einen Markdown-Absatz, Listenpunkt oder einer Kopfzeile verwendet werden. HTML-Tags können sogar statt der entsprechenden Markdown-Formatierung verwendet werden. Es ist kein Problem, statt Markdows Syntax für Links oder Grafiken einfach <a> oder <img> zu verwenden.
Im Gegensatz zu Block-Tags wird die Markdown-Syntax innerhalb von Inline-Tags interpretiert.
Beispiel:
This is a paragraph of text.
<p>This is a <span style="font-weight: bold;">paragraph</span> of text.</p>
¶ Automatische Maskierung besonderer Zeichen
In HTML gibt es zwei Zeichen, die einer besonderen Behandlung bedürfen: < und &. Die linke spitze Klammer wird verwendet um HTML-Tags zu öffnen, das kaufmännische Und wird verwendet um benannte Zeichen (Entities) zu beschreiben. Wenn diese Zeichen in HTML-Dokumenten als "sie selbst" verwendet werden sollen, müssen sie als Entities maskiert werden, also als < und &.
Das kaufmännische Und ist besonders unpraktisch für Web-Entwickler. Will man über "AT&T" schreiben, muss man "AT&T" schreiben. Das kaufmännische Und muss sogar in URLs maskiert werden. In einem Link zur Seite
http://website.com/images?num=30&q=larry+bird
muss die URL wie folgt kodiert werden:
http://website.com/images?num=30&amp;q=larry+bird
Dies ist einfach zu vergessen und vermutlich der beliebteste Fehler bei der Validierung von ansonsten wohlgeformten HTML-Dokumenten.
Markdown erlaubt es, diese Zeichen ganz normal zu benutzen. Es regelt die Kodierung selbst. Wenn ein Kaufmanns-Und in einem Entity verwendet wird, wird es nicht kodiert, sonst zu & umgewandelt.
Wenn man also zum Beispiel ein Copyright-Symbol eingeben will, kann man einfach
&copy;
©
AT&T
schreiben, und Markdown wird dies nicht modifizieren. Aber aus
AT&T
wird Markdown
AT&amp;T
machen. Da Markdown Inline HTML unterstützt, werden spitze Klammern im entsprechenden Fall ganz normal als HTML behandelt. Nur aus Sachen wie
4 < 5
wird Markdown
4 &lt; 5
machen. In Code- oder Span-Blöcken werden spitze Klammern und das kaufmännische Und jedoch immer kodiert. Dies vereinfacht das Schreiben über HTML in Markdown (Im Gegensatz zu rohem HTML, wo es meist ein Alptraum ist, jedes < und & zu kodieren).
¶ Block-Elemente
¶ Absätze und Zeilenumbrüche
Ein Absatz besteht einfach aus einer oder aus mehreren Zeilen von Text, abgetrennt durch eine oder mehrere leere Zeilen. (Eine leere Zeile ist jede Zeile die aussieht wie eine leere Zeile -- eine Zeile die nichts anderes enthält als Leerzeichen und Tabs wird als leer behandelt.) Normale Absätze sollten nicht mit Leerzeichen oder Tabs eingerückt sein.
Die "eine oder mehrere Zeilen"-Regel impliziert eine Sache: Markdown unterstützt Absätze mit "harten Umbrüchen". Dies ist ein großer Unterschied zu den meisten anderen Text-zu-HTML-Formatierern (inklusive der "Convert Line Breaks" Option von Movable Type), die jeden Zeilenumbruch in einem Absatz als <br /> formatieren.
Wenn man ein <br /> als Umbruch haben will, kann man die Zeile einfach mit zwei oder mehr Leerzeichen beenden.
Dies ist zwar ein kleiner Mehraufwand um ein <br /> zu erzeugen, aber eine einfache "jeder Zeilenumbruch ist ein <br />" Regel würde in Markdown nicht funktionieren.
Markdowns Email-artige Zitate und Listen-Einträge mit mehreren Absätzen funktionieren am Besten - und sehen besser aus -- wenn sie mit Zeilenumbrüchen formatiert werden.
¶ Kopfzeilen
Markdown unterstützt zwei Arten von Kopfzeilen-Formatierung, Setext und atx.
Setext-artige Kopfzeilen werden mit Gleichheitszeichen (für Überschriften erster Ebene) und Bindestrichen (für die zweite Ebene) "unterstrichen". Zum Beispiel:
Dies ist ein H1
===============
Dies ist ein H2
---------------
Eine beliebige Zahl von = oder - funktioniert.
Atx-artige Kopfzeilen verwenden 1-6 Rauten-Zeichen am Anfang der Zeile, entsprechend den Ebenen 1-6. Zum Beispiel:
# Dies ist ein H1
## Dies ist ein H2
###### Dies ist ein H6
Wenn gewünscht können atx-artige Kopfzeilen auch "geschlossen" werden. Dies ist nur Kosmetik -- es kann genutzt werden wenn es besser aussieht. Die Zahl der schließenden Rauten-Zeichen muss nicht einmal der Zahl der öffnenden Zeichen entsprechen.
# Dies ist ein H1 #
## Dies ist ein H2 ##
### Dies ist ein H3 ######
¶ Zitate
Markdown verwendet - wie E-Mails - das Zeichen > für Zitat-Blöcke. Wenn man Erfahrung mit Zitaten in E-Mails hat, weiß man auch wie man Zitate in Markdown erstellt. Es sieht am Besten aus wenn man den Text pro Zeile umbricht und ein > vor jede Zeile setzt:
> Dies ist ein Zitat mit zwei Absätzen. Lorem ipsum dolor sit amet,
> consectetuer adipiscing elit. Aliquam hendrerit mi posuere
> lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet
> vitae, risus.
>
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
> Suspendisse id sem consectetuer libero luctus adipiscing.
Markdown erlaubt aber auch faul zu sein und das > nur auf der ersten Zeile eines hart umgebrochenen Absatzes zu verwenden:
> Dies ist ein Zitat mit zwei Absätzen. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae,
risus.
> Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
Zitate können verschachtelt werden (also Zitat in einem Zitat) indem man mehr > verwendet:
> Dies ist die erste Zitat-Ebene.
>
> > Dies ist ein verschachteltes Zitat.
>
> Zurück auf der ersten Ebene.
Zitate können andere Markdown-Elemente enthalten, darunter Kopfzeilen, Listen und Code-Blöcke:
> ## Dies ist eine Überschrift.
>
> 1. Dies ist der erste Listenpunkt.
> 2. Dies ist der zweite Listenpunkt.
>
> Hier ist ein wenig Beispiel-Code:
>
> return shell_exec("echo $input | $Markdown_script");
Jeder vernünftige Text-Editor sollte das Zitieren im Stil von E-Mail einfach machen. In BBEdit zum Beispiel kann man eine Auswahl machen und aus dem Menü Text den Punkt Increase Quote Level wählen.
¶ Listen
Markdown unterstützt sortierte (nummerierte) und unsortierte Listen (Aufzählungen).
Unsortierte Listen benutzen Sternchen, Plus und Bindestriche -- austauschbar -- als Listen-Marker:
* Rot
* Grün
* Blau
ist gleich:
+ Rot
+ Grün
+ Blau
Und:
- Rot
- Grün
- Blau
Sortierte Listen verwenden Zahlen mit darauf folgendem Punkt:
1. Hund
2. Katze
3. Maus
Hierbei ist es wichtig zu verstehen, dass die Zahlen selber keine Auswirkung auf den Output von Markdown hat. Markdown erstellt aus der letzten Liste folgenden HTML-Code:
<ol>
<li>Hund</li>
<li>Katze</li>
<li>Maus</li>
</ol>
Wenn man die Liste statt dessen so schreibt:
1. Hund
1. Katze
1. Maus
Oder sogar:
3. Hund
1. Katze
8. Maus
kommt trotzdem jedes Mal die gleiche Liste heraus. Wenn gewünscht, kann man seine Listen von Hand richtig nummerieren. Aber wer faul sein will, kann getrost immer die gleiche Ziffer benutzen.
Allerdings sollte man auch dann die Liste mit der Nummer 1 beginnen. In Zukunft wird Markdown vielleicht eine Startziffer für den ersten Listeneintrag festlegen wollen.
Listeneinträge beginnen normalerweise am linken Rand des Dokuments, sie können jedoch bis zu drei Leerzeichen nach Rechts eingerückt sein. Listen-Marker müssen mit ein oder mehr Leerzeichen oder einem Tab vom folgenden Text getrennt werden.
Um Listen schön zu formatieren, können die einzelnen Einträge weiter eingerückt werden, so wie hier:
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
Das folgende Beispiel generiert den gleichen Code, ist aber weniger aufgeräumt:
* Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
viverra nec, fringilla in, laoreet vitae, risus.
* Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
Suspendisse id sem consectetuer libero luctus adipiscing.
Wenn Listeinträge durch Leerzeilen getrennt sind, wird Markdown die Listeneinträge mit <p> und </p> umhüllen.
Zum Beispiel wird dies:
* Warsteiner
* König
zu
<ul>
<li>Warsteiner</li>
<li>König</li>
</ul>
Aber dies:
* Warsteiner
* König
wird zu
<ul>
<li><p>Warsteiner</p></li>
<li><p>König</p></li>
</ul>
Listenpunkte können aus mehreren Absätzen bestehen. Jeder folgende Absatz in einem Listenpunkt muss mit mindestens 4 Leerzeichen oder einem Tab eingerückt werden:
1. Dies ist eine Listenpunkt mit zwei Absätzen. Lorem ipsum dolor
sit amet, consectetuer adipiscing elit. Aliquam hendrerit
mi posuere lectus.
Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
sit amet velit.
2. Suspendisse id sem consectetuer libero luctus adipiscing.
Es sieht gut aus wenn jede Zeile des folgenden Absatzes eingerückt ist, aber wieder erlaubt Markdown dem Faulen, nur die erste Zeile einzurücken:
* Dies ist ein Listenpunkt mit zwei Absätzen
Dies ist der zweite Absatz in diesem Listenpunkt. Nur die
erste Zeile muss eingerückt sein. Lorem ipsum dolor sit amet,
consectetuer adipiscing elit.
* Ein weiterer Punkt in der selben Liste.
Um ein Zitat in einem Listenpunkt zu verwenden muss das Zitat eingerückt werden:
* Ein Listenpunkt mit einem Zitat:
> Dies ist ein Zitat
> In einer Liste.
Um einen Code-Block in einem Listenpunkt zu verwenden muss er zwei mal eingerückt werden -- 8 Leerzeichen oder zwei Tabs:
* Ein Listenpunkt mit Codebeispiel:
<hier Code einfügen>
Es ist möglich Listen unabsichtlich zu erstellen, indem man z.B. folgendes schreibt:
1986. Was für ein wundervolles Jahr.
Mit anderen Worten: Die Sequenz Zahl-Punkt-Leerzeichen am Anfang einer Zeile. Um dieses Problem zu vermeiden kann der Punkt per Backslash maskiert werden:
1986\. Was für ein wundervolles Jahr.
¶ Code-Blöcke
Vorformatierte Code-Blöcke werden verwendet um über Programm- oder Markup-Quelltext zu schreiben. Statt normale Absätze zu bilden werden die Zeilen in einem Code-Block wie vorgefunden interpretiert. Markdown umfasst Code-Blöcke mit den Tags <pre> und <code>.
Um einen Code-Block in Markdown zu erstellen, wird einfach jede Zeile des Blocks mit mindestens 4 Leerzeichen oder einem Tab eingerückt. Aus folgender Eingabe...
Dies ist ein normaler Absatz.
Dies ist ein Code-Block.
...macht Markdown folgendes:
<p>Dies ist ein normaler Absatz.</p>
<pre><code>Dies ist ein Code-Block.
</code></pre>
Eine Stufe der Einrückung -- 4 Leerzeichen oder 1 Tab -- werden von jeder Zeile der Einrückung entfernt. Folgendes zum Beispiel...
Ein Beispiel in AppleScript:
tell application "Foo"
beep
end tell
...wird zu
<p>Ein Beispiel in AppleScript:</p>
<pre><code>tell application "Foo"
beep
end tell
</code></pre>
Ein Code-Block endet bei der ersten Zeile, die nicht eingerückt ist (oder am Ende des Dokuments).
In einem Code-Block werden das kaufmännische Und (&) und spitze Klammern (< und >) automatisch in HTML-Entities umgewandelt. Dies erleichtert die Einbindung von HTML-Stücken ungemein -- einfach HTML in das Dokument kopieren, einrücken und Markdown erledigt die Kodierung des kaufmännischen Unds und der spitzen Klammern. Zum Beispiel:
<div class="footer">
&copy; 2004 Foo Corporation
</div>
wird zu:
<pre><code>&lt;div class="footer"&gt;
&amp;copy; 2004 Foo Corporation
&lt;/div&gt;
</code></pre>
Normale Markdown-Syntax wird in Code-Blöcken nicht verarbeitet. D.h. Sternchen sind einfach nur Sternchen in einem Code-Block und nicht das Signal, den Text hervorzuheben. Die Konsequenz ist, dass es einfach ist, in Markdown über Markdown zu sprechen.
¶ Horizontale Linien
Der Tag für horizontale Linien (<hr />) kann generiert werden indem 3 oder mehr Bindestriche oder Sternchen allein auf einer Zeile geschrieben werden. Leerzeichen zwischen den Zeichen sind auch erlaubt. Alle folgenden Beispiele würden eine horizontale Linie generieren:
* * *
***
*****
- - -
---------------------------------------
¶ Span-Elemente
¶ Links
Markdown unterstützt zwei Arten von Links: Inline und Referenzen.
In beiden Stilen wird der Link-Text mit [eckigen Klammern] markiert.
Um einen Inline-Link zu erstellen schreibt man direkt hinter der schließenden eckigen Klammer normale Klammern. In diese Klammern wird die URL geschrieben auf die verlinkt werden soll zusammen mit einem optionalen Titel für den Link in Anführungsstrichen. Beispiele:
Dies ist [ein Beispiel](http://example.com/ "Der Linktitel") für
einen Inline-Link.
[Dieser Link](http://example.net/) hat kein Titel-Attribut.
Daraus wird:
<p>Dies ist <a href="http://example.com/" title="Der Linktitel">
ein Beispiel</a> für einen Inline-Link.</p>
<p><a href="http://example.net/">Dieser Link</a> hat kein
Titel-Attribut.</p>
Wenn man auf Inhalte auf dem gleichen Server verweisen will, kann man relative Pfade verwenden:
Auf der Seite [Über mich](/about/) gibt es weitere Informationen.
Referenz-Links verwenden einen zweiten Satz eckige Klammern in die ein beliebig gewählter Bezeichner für den Link geschrieben wird:
Dies ist [ein Beispiel][id] für einen Referenz-Link.
Nach Belieben kann auch ein Leerzeichen zwischen den Klammern eingefügt werden:
Dies ist [ein Beispiel] [id] für einen Referenz-Link.
Dann, irgendwo im Dokument, wird der Link wie folgt auf einer eigenen Zeile definiert:
[id]: http://example.com/ "Optionalen Titel hier eintragen"
Also:
- Eckige Klammern welche den Link-Bezeichner enthalten (wahlweise mit mit bis zu drei Leerzeichen eingerückt);
- gefolgt von einem Doppelpunkt;
- gefolgt von einem oder mehreren Leerzeichen (oder Tabs);
- gefolgt von der URL für den Link;
- optional gefolgt vom Text für das Titel-Attribut des Links, gehüllt in Klammern, einzelne oder doppelte Anführungsstriche.
Die folgenden drei Definitionen sind identisch:
[foo]: http://example.com/ "Optionaler Titel"
[foo]: http://example.com/ 'Optionaler Titel'
[foo]: http://example.com/ (Optionaler Titel)
Anmerkung: Es existiert bekannter Bug in Markdown 1.0.1 der die Funktion von einzelnen Anführungszeichen als Trenner für Link-Titel behindert.
Die Link-URL kann wahlweise in spitzen Klammern verpackt werden:
[id]: <http://example.com/> "Optionaler Titel hier"
Das Titel-Attribut kann auch auf die nächste Zeile gesetzt und mit mehr Leerzeichen oder Tabs eingerückt werden. Dies sieht mit langen URLs besser aus:
[id]: http://example.com/langer/pfad/zu/seite
"Optionaler Titel hier"
Link-Definitionen werden nur verwendet um Links zu erstellen während Markdown das Dokument verarbeitet und werden aus dem Dokument entfernt bevor das HTML ausgegeben wird.
Die Bezeichner für Link-Definitionen dürfen aus Buchstaben, Zahlen, Leerzeichen und Satzzeichen bestehen. Sie sind unabhängig von Groß- und Kleinschreibung:
[Link-Text][a]
[Link-Text][A]
Die beiden Link-Definitionen sind äquivalent.
Der implizierte Link-Bezeichner erlaubt das Auslassen des Link-Bezeichers. In diesem Fall wird der Link-Text als Bezeichner verwendet. Es wird einfach ein leerer Satz eckige Klammern an den Link-Text angefügt:
[Google][]
Dann wird der Link definiert:
[Google]: http://google.com/
Da Link-Bezeichner Leerzeichen enthalten dürfen, funktioniert diese Abkürzung sogar für mehrere Wörter im Link-Text:
Besuchen Sie [Daring Fireball][] für weitere Informationen.
Dann wird der Link definiert:
[Daring Fireball]: https://daringfireball.net/
Link-Definitionen können an einen beliebige Stelle im Markdown-Dokument gemacht werden. Generell ist es eine gute Idee, sie nach dem Absatz zu machen, in dem sie verwendet werden. Sie können aber auch wie Fußnoten alle zusammen am Ende des Dokuments aufgelistet werden.
Ein kleines Beispiel:
Ich bekomme zehn Mal mehr Traffic von [Google] [1] als von
[Yahoo] [2] oder [MSN] [3].
[1]: http://google.com/ "Google"
[2]: http://search.yahoo.com/ "Yahoo Search"
[3]: http://search.msn.com/ "MSN Search"
Mit der Abkürzung über den implizierten Link-Bezeichner kann man auch folgendes Schreiben:
Ich bekomme zehn Mal mehr Traffic von [Google][] als von [Yahoo][] oder [MSN][].
[google]: http://google.com/ "Google"
[yahoo]: http://search.yahoo.com/ "Yahoo Search"
[msn]: http://search.msn.com/ "MSN Search"
Beide Beispiele würden folgenden HTML-Code ergeben:
<p>Ich bekomme zehn Mal mehr Traffic von <a href="http://google.com/"
title="Google">Google</a> als von
<a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
oder <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
Zum Vergleich folgt der gleiche Absatz unter Verwendung von Markdowns Inline-Links:
Ich bekomme zehn Mal mehr Traffic von [Google](http://google.com/ "Google")
als von [Yahoo](http://search.yahoo.com/ "Yahoo Search") oder
[MSN](http://search.msn.com/ "MSN Search").
Die Idee hinter Referenz-Links ist nicht, dass sie einfacher zu schreiben sind. Die Idee ist, dass sie Dokumente weitaus lesbarer machen. Der Beispiel-Absatz ist mit Referenz-Links nur 80 Zeichen lang, mit Referenz-Links ist er ganze 181 Zeichen lang; als HTML sind es 239 Zeichen, mehr Markup als Inhalt.
Mit Markdowns Referenz-Links ähnelt das Quell-Dokument eher dem endgültigen Ausgabeformat, wie es im Browser gezeigt wird. Durch die Möglichkeit, Metadaten für Markup aus dem Absatz rauszuholen können Links in den Text integriert werden ohne den Textfluss zu bremsen.
¶ Betonung
Markdown behandelt Sternchen (*) und Unterstriche (_) als Indikatoren für Betonung. In einzelne * oder _ gepackter Text wird mit dem HTML-Tag <em> umschlossen, doppelte * oder _ werden mit dem Tag <strong> markiert. Folgender Text zum Beispiel:
*Einzelne Sternchen*
_Einzelne Unterstriche_
**Doppelte Sternchen**
__Doppelte Unterstriche__
Wird folgendes ausgeben:
<em>Einzelne Sternchen</em>
<em>Einzelne Unterstriche</em>
<strong>Doppelte Sternchen</strong>
<strong>Doppelte Unterstriche</strong>
Der Stil kann beliebig gewählt werden. Die einzige Begrenzung ist, dass das gleiche Zeichen zum Öffnen und Schließen eines Betonungsbereiches verwendet werden muss.
Betonung kann inmitten eines Wortes verwendet werden:
Herr*gott*sakrament
Aber wenn ein * oder _ von Leerzeichen umgeben ist, wird es wie ein einfaches Sternchen oder ein einfacher Unterstrich behandelt.
Um ein Sternchen oder einen Unterstrich zu schreiben an einer Stelle wo er als Betonung verstanden würde, kann er mit einem Backslash maskiert werden:
\*Dieser Text ist von Sternchen umschlossen.\*
¶ Code
Um einen Code-Bereich zu markieren, wird er mit Backtick-Zeichen umschlossen (`). Im Gegensatz zu einem Code-Block formatiert ein Code-Bereich Code innerhalb eines normalen Absatzes:
Benutze die Funktion `printf()` um Text auszugeben.
Wird zu:
<p>Benutze die Funktion <code>printf()</code> um Text auszugeben.</p>
Wenn ein Backtick im Code-Bereich dargestellt werden soll, dann können mehrere Backticks vor und nach dem Code-Bereich verwendet werden:
``Irgendwo hier (`) ist ein Backtick versteckt.``
Dies wird zu:
<p><code>irgendwo hier (`) ist ein Backtick versteckt.</code></p>
Die Backtick-Trennzeichen um einen Code-Bereich können Leerzeichen enthalten -- eins nach den öffnenden, eins vor dem schließenden Backticks. Dies ermöglicht die Verwendung von Backticks innerhalb des Code-Bereiches auch am Anfang oder Ende:
Ein einzelner Backtick in einem Code-Bereich: `` ` ``
Ein Backtick-umschlossener String in einem Code-Bereich: `` `foo` ``
wird zu:
<p>Ein einzelner Backtick in einem Code-Bereich: <code>`</code></p>
<p>Ein Backtick-umschlossener String in einem Code-Bereich: <code>`foo`</code></p>
In Code-Bereichen werden das kaufmännische Und so wie spitze Klammern als HTML-Entitiy kodiert.
Niemand benutzt `<blink>` Tags.
Dies wird zu:
<p>Niemand benutzt <code>&lt;blink&gt;</code> Tags.</p>
Auch folgendes funktioniert:
`&#8212;` ist das dezimal kodierte Äquivalent von `&mdash;`.
Dies wird zu
<p><code>&amp;#8212;</code> ist das dezimal kodierte
Äquivalent von <code>&amp;mdash;</code>.</p>
¶ Grafiken
Zugegebenermaßen ist es recht schwierig, eine "natürliche" Syntax für das Einbinden von Grafiken in Text zu finden.
Markdown verwendet hierzu eine Syntax, die dem Stil von Links ähneln soll. Dies erlaubt zwei Arten: Inline und Referenz.
Die Inline-Syntax sieht so aus:
Also:
- Ein Ausrufezeichen:
!; - gefolgt von einem Satz eckiger Klammern die den Wert des
alt-Attributes für die Grafik enthalten; - gefolgt von runden Klammern, welche die URL oder den Pfad zur Grafik enthalten sowie den Wert eines optionalen
title-Attributes, verpackt in Anführungsstriche.
Bildverweise im Referenz-Stil sehen wie folgt aus:
![Alternativer Text][id]
"id" ist hier der Name einer definierten Bild-Referenz. Bild-Referenzen werden mit dem gleicher Syntax definiert wie Link-Referenzen:
[id]: url/zur/grafik "Optionales title-Attribut"
Zur Zeit besitzt Markdown keine Syntax um die Größe einer Grafik anzugeben. Sollte dies nötig sein kann einfach der normale HTML-Tag <img> verwendet werden.
¶ Verschiedenes
¶ Automatische Links
Markdown unterstützt einen einfachen Stil um "automatisch" Links für URLs und eMail-Adressen zu generieren: Die URL oder eMail-Adresse wird einfach von spitzen Klammern umschlossen. Wenn man eine URL oder Mailadresse direkt zeigen will, kann man dies so lösen:
<http://example.com/>
Markdown wird dies in den folgenden HTML-Code umsetzen:
<a href="http://example.com/">http://example.com/</a>
Automatische Links für eMail-Adressen funktionieren ähnlich, nur das Markdown hier per Zufallsprinzip die Adresse in dezimale und hexadezimale Entity-Kodierung umwandelt um dabei zu helfen, die Adresse für Spambots unzugänglich zu machen. Zum Beispiel:
<address@example.com>
Dies wird zu so etwas wie dem Folgenden:
<a href="&#x6D;&#x61;i&#x6C;&#x74;&#x6F;:&#x61;&#x64;&#x64;&#x72;&#x65;
&#115;&#115;&#64;&#101;&#120;&#x61;&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;
&#109;">&#x61;&#x64;&#x64;&#x72;&#x65;&#115;&#115;&#64;&#101;&#120;&#x61;
&#109;&#x70;&#x6C;e&#x2E;&#99;&#111;&#109;</a>
Im Browser wird dies als klickbarer Link zur Adresse "address@example.com" erscheinen.
(Dieser Trick wird viele, wenn nicht die meisten, Adressen-Sammler abschmettern. Aber er wird definitiv nicht alle erwischen. Es ist besser als nichts, aber irgendwann wird eine so publizierte Adresse auch Spam zugesandt bekommen.)
¶ Backslash-Maskierung
Markdown ermöglicht es, Backslash-Maskierung zu nutzen um Zeichen zu schreiben, die sonst eine bestimmte Bedeutung in Markdowns Syntax haben. Wenn man zum Beispiel ein Wort mit Sternchen umgeben will (statt dem HTML-Tag <em>), kann man Backslashes vor die Sternchen stellen:
\*Von Sternchen umgeben\*
Markdown bietet diese Möglichkeit für folgende Zeichen:
\ Backslash
` Backtick
* Sternchen
_ Unterstrich
{} Geschweifte Klammern
[] Eckige Klammern
() Runde Klammern
# Raute
+ Plus-Zeichen
- Minus-Zeichen (Bindestrich)
. Punkt
! Ausrufezeichen
¶ Interna
Diese Informationen beziehen sich ausschließlich auf diese Übersetzung der Markdown-Dokumentation, nicht auf die Englische Vorlage, Markdown.pl selbst oder andere Dokumente.
¶ Ergänzung zu den allgemeinen AGBs
¶ Lizenz
Dieses Werk ist lizenziert unter einer Creative Commons Namensnennung - Weitergabe unter gleichen Bedingungen (BY-SA) 4.0 International Lizenz.
Der Fußnoten-Text kann am Seiten-Ende platziert werden. ↩︎