Markdown Dokumentation

Letzte Änderung: 15. Dezember, 2016

Was ist Markdown

Markdown ermöglicht eine Formatierung in Klartext. D.h. sie schreiben schnell und einfach strukturierte Inhalte für das Web. Diese Inhalte werden von einem Markdown-Parser in sauberes HTML konvertiert. Die Konvertierung erfolgt automatisch beim Anzeigen der Website.

Der *rote* Fuchs, sprang **über** den faulen [Hund](https://en.wikipedia.org/wiki/Dog).

Wird zu folgender Ausgabe:

Der rote Fuchs, sprang über den faulen Hund.

HTML-Code:


<p>Der <em>rote</em> Fuchs, sprang <strong>über</strong> 
den faulen <a href=“https://en.wikipedia.org/wiki/Dog“>Hund</a>.</p>
									

Mit nur wenigen Zeichen, kann mit Markdown eine schöne Formatierung erreicht werden.

Warum lieben Autoren Markdown?

Sie behaupten, mit einen HTML-Editor erreicht man mit wenigen Klick das selbe Ergebnis? Das mag sein, aber die Vielzahl an Formatierungswerkzeugen hat seit einigen Jahren erheblich verändert. Die meisten Anfänger möchten gerne über Buttons und komplexe Menüs die Formatierungen erstellen. Fortgeschrittene Autoren schwören auf Markdown, weil es zu einem fließenden Schreibstil führt.

Mit einem herkömmlichen HTML-Tools müssen Sie das Schreiben immer wieder unterbrechen, um die Buttons und Menüs für die Formatierung zu bedienen. Dies führt zu einem unruhigen Arbeiten, zu unnötigem Stress und kostest viel Zeit.

Markdown ermöglicht es, die Finger auf der Tastatur zu lassen, weil sie die Formatierung „on-the-fly„ anwenden und der Schreibfluss nicht unterbrochen wird. Sie müssen für die Formatierung das Schreiben nicht unterbrechen, oder sich Gedanken machen, mit welchen Stilen sie nun die Formatierung noch umsetzen müssen.

Haben sie sich erst einmal umgestellt und an diesen Schreibstil gewöhnt, möchten sie nie wieder zurück zur reinen HTML-Formatierung bzw. zurück zum Arbeiten mit HTML-Editoren.

Überschriften

Für Überschriften auf der ersten Ebene, unterstreichen sie den Text mit Gleichheits-Zeichen.
Für Überschriften auf der zweiten Ebene, nutzen sie Minus-Zeichen.
Diese Art der Überschriften-Formatierung nennt man den ATX-Style und kann nur für H1 und H2 verwendet werden.

Dies ist ein(e) H1
==================

Dies ist ein(e) H1

Dies ist ein(e) H2
------------------

Dies ist ein(e) H2

Alternativ können sie für Überschriften auch den Präfix "hash" (#), oder auch Setext-Style genannt, nutzen. Die Nummer des hash-Symbols ist dabei die Ebene der Überschrift. Zum Beispiel bedeutet ein einzelnes hash eine Überschrift auf der ersten Ebene, während zwei eine Überschrift auf der zweiten Ebene kennzeichnen:

# Dies ist ein(e) H1

Dies ist ein(e) H1

## Dies ist ein(e) H2

Dies ist ein(e) H2

### Dies ist ein(e) H3

Dies ist ein(e) H3

#### Dies ist ein(e) H4

Dies ist ein(e) H4

##### Dies ist ein(e) H5
Dies ist ein(e) H5
###### Dies ist ein(e) H6
Dies ist ein(e) H6

Absätze und Paragraphen

Einen Umbruch in Form eines <br />, erreicht man, indem man am Ende einer Zeile zwei oder mehr Leerzeichen verwendet.
Absätze werden erzeugt, indem man eine Leerzeile zwischen den Zeilen verwendet.

Der rote Fuchs,
sprang über den faulen Hund.
<P>Der rote Fuchs, sprang über den faulen Hund.</P>
Der rote Fuchs,  (min. 2 Leezeichen am Ende)
sprang über den faulen Hund.
<P>Der rote Fuchs,<br>
sprang über den faulen Hund.</P>
Der rote Fuchs,

sprang über den faulen Hund.
<P>Der rote Fuchs,<P>
<P>sprang über den faulen Hund.<P>

Textauszeichnungen

Fett

Um fetten Text zu erstellen, umschließen sie den Texte entweder mit zwei Sternsymbolen (**), oder mit zwei Unterstrichen (__):

Dieser Text ist **fett** ausgezeichnet! Dieser Text ist fett ausgezeichnet!
Dieser Text ist ebenfalls __fett__ ausgezeichnet! Dieser Text ist ebenfalls fett ausgezeichnet!

Kursiv

Um kursiven Text zu erstellen, umschließen sie den Texte entweder mit einem Sternsymbol (*), oder mit einem Unterstrich (_):

Dieser Text ist *kursiv* ausgezeichnet! Dieser Text ist kursiv ausgezeichnet!
Dieser Text ist ebenfalls _kursiv_ ausgezeichnet! Dieser Text ist ebenfalls kursiv ausgezeichnet!

Fett+Kursiv

Um kursiven Text zu erstellen, umschließen sie den Texte entweder mit drei Sternsymbolen (***), oder mit drei Unterstrichen (___):

Dieser Text ist ***fett+kursiv*** ausgezeichnet! Dieser Text ist fett+kursiv ausgezeichnet!
Dieser Text ist ebenfalls ___kursiv___ ausgezeichnet! Dieser Text ist ebenfalls fett+kursiv ausgezeichnet!

Unterstrichen

Unterstreichungen werde oft fälschlicherweise zur Hervorhebung von Texten verwendet. Laut HTML5-Spezifikation sollte man Unterstreichnungen ausschließlich für Hyperlinks verwenden. Seit HTML 4.01 ist das <u> Element veraltet (deprecated)!

In HTML5 sind Unterstreichungen nur für Außnahmen wie falsch geschriebene Wörter oder Eigennamen auf Chinesisch erlaubt. D.h. für Text, der sich stilistisch stark vom normalen Text unterscheiden soll.

In Markdown ist aus diesen Gründen eine underline-Formatierung nicht vorgesehen. Hyperlinks und Referenzen werden automatisch durch die jeweiligen CSS-Styles definiert. Benötigen sie dennoch eine Unterstreichung, müssen sie auf Standard-HTML zurückgreifen.

Aufzählungen

Aufzählungen beginnen durch eine Leerzeile und die Listenpunkte stehen in eigenen Zeilen, die mit *, - oder + (unnummerierte Liste) bzw. 1. (nummerierte Liste) eingeleitet werden, gefolgt von einem Leerzeichen.

Bitte beachten sie das Leerzeichen! Vergessen sie das Leezeichen, hat das *-Zeichen eine völlig andere Bedeutung.

Unterlistenpunkte werden mit mind. 4 Leerzeichen eingerückt. Dabei ist vollkommen egal, welche Zahl verwendet wird, da die Elemente der Reihenfolge nach automatisch durchnummeriert werden.

Ungeordnete Listen

- Einkaufen gehen
- Schuhe putzen
+ Wäsche waschen
+ Fahrrad reparieren
  • Einkaufen gehen
  • Schuhe putzen
  • Wäsche waschen
  • Fahrrad reparieren
* Reifen wechseln
* Ölstand checken
  • Reifen wechseln
  • Ölstand checken

Geordnete Listen

1. Einkaufen gehen
2. Schuhe putzen
3. Wäsche waschen
4. Fahrrad reparieren
  1. Einkaufen gehen
  2. Schuhe putzen
  3. Wäsche waschen
  4. Fahrrad reparieren

Verschachtelte Listen

1. Einkaufen gehen
    - Kartoffeln
    - Zwiebeln
2. Kochen
    1. Schnippeln
    2. Braten
3. Genießen
4. Fahrrad reparieren
  1. Einkaufen gehen
    • Kartoffeln
    • Zwiebeln
  2. Kochen
    1. Schnippeln
    2. Braten
  3. Genießen
  4. Fahrrad reparieren

Bilder

Zugegebenermaßen ist es recht schwierig, eine „natürliche“ Syntax für das Einbinden von Grafiken in einfachem Textstyle 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:

![Alternativer Text](/pfad/zum/bild.jpg)
![Alternativer Text](/pfad/zum/bild.jpg „Optionaler Titel“)

Also:

  1. Ein Ausrufezeichen: !
  2. gefolgt von einem Satz eckiger Klammern die den Wert des alt-Attributes für die Grafik enthalten;
  3. 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 der gleichen Syntax definiert wie Link-Referenzen:
[id]: url/zur/grafik „Optionales title-Attribut“

Zur Zeit besitzt Markdown keine Syntax um die Größe einer Grafik zu definieren. Sollte dies zwingend nötig sein, muss man auf das normale HTML-Tag <img> zurückgreifen.

Tabellen

Für Tabellen werden senkrechte Striche (pipe, |) zur Abgrenzung der Spalten und Bindestriche (-) zur Abgrenzung des Tabellenkopfes (<thead>) von Tabellenkörper (<thody>) eingesetzt. Das folgende Beispiel zeigt dies.

Spalte 1 | Spalte 2 | Spalte 3
-------- | -------- | --------
Inhalt | Inhalt | Inhalt
Inhalt | Inhalt | Inhalt

Hier sehen Sie den HTML-Quelltext, der aus dem vorherigen Beispiel erzeugt wird:


 <table>
  <thead>
    <tr>
      <th>Spalte 1</th>
      <th>Spalte 2</th>
      <th>Spalte 3</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Inhalt</td>
      <td>Inhalt</td>
      <td>Inhalt</td>
    </tr>
    <tr>
      <td>Inhalt</td>
      <td>Inhalt</td>
      <td>Inhalt</td>
    </tr>
  </tbody>
</table>										
										

Markdown bietet auch die Möglichkeit, an den Anfang und an das Ende jeder Zeile Pipes (|) zu setzen. Die Ausgabe ändert sich dadurch nicht. Es sieht nur für den ein oder anderen beim Bearbeiten der Tabelle besser aus.

| Spalte 1 | Spalte 2 | Spalte 3 |
| -------- | -------- | -------- |
| Inhalt | Inhalt | Inhalt |
| Inhalt | Inhalt | Inhalt |

Wie Sie gesehen haben, sind bei den letzten Beispielen die Spalten in jeder Zeile immer schön exakt gleich lang. Das hat allerdings rein ästhetische Gründe und dient der besseren Lesbarkeit der Tabelle im Rohzustand. Beim Bearbeiten der Tabelle sind Sie also nicht gezwungen, die Spalten in jeder Zeile exakt jedentisch lang zu machen. Das folgende Beispiel zeigt dies.

| Spalte 1 | Das ist Spalte 2 | Und hier ist Spalte 3 |
| -------- | -------- | -------- |
| Inhalt | Das ist ein ganz langer Inhalt. | Auch hier steht ein langer Text. |
| Inhalt | Inhalt | Inhalt |

Innerhalb einer Tabelle kann man wiederum auch Standard-Markdown verwenden. Im folgenden Beispiel wird Text als kursiv (*), fett (**) und durchgetsrichen (~~) markiert.

Spalte 1 | Spalte 2 | Spalte 3
-------- | ---------- | ----------
*Inhalt* | **Inhalt** | ~~Inhalt~~
Inhalt | Inhalt | Inhalt

Markdown bietet Ihnen zusätzlich die Möglichkeit, Text innerhalb einer Spalte nach links, mittig oder nach rechts auszurichten. Dazu setzen Sie bei der Trennline zwischen Tabellenkopf und Tabellenkörper Duppelpunkte (:) auf die Seite, nach der ausgerichtet werden soll. Bei der Textzentrierung setzen Sie auf beiden Seiten einen Doppelpunkt.

| Links ausgerichtet | Mittig ausgerichtet | Rechts ausgerichtet |
|:------------------ |:-------------------:| -------------------:|
| Inhalt | Inhalt | Inhalt |
| Inhalt | Inhalt | Inhalt |

Hier sehen Sie den HTML-Quelltext, der aus dem vorherigen Beispiel erzeugt wird:


  <table>
  <thead>
    <tr>
      <th style=“text-align: left“>Links ausgerichtet</th>
      <th style=“text-align: center“>Mittig ausgerichtet</th>
      <th style=“text-align: right“>Rechts ausgerichtet</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style=“text-align: left“>Inhalt</td>
      <td style=“text-align: center“>Inhalt</td>
      <td style=“text-align: right“>Inhalt</td>
    </tr>
    <tr>
      <td style=“text-align: left“>Inhalt</td>
      <td style=“text-align: center“>Inhalt</td>
      <td style=“text-align: right“>Inhalt</td>
    </tr>
  </tbody>
</table>
										

Quelltext

Markdown bietet Ihnen eine einfache Möglichkeit, Quelltext innerhalb eines Textes kenntlich zu machen. Sie müssen dazu den Quelltext mit Backtick-Zeichen (`) umschließen. Das folgende Beispiel zeigt dies.

Verwenden Sie die `echo`-Funktion.

Durch dieses Markdown-Beispiele wird folgender HTML-Quelltext erzeugt.


<p>Verwenden Sie die <code>echo</code>-Funktion.</p>

Backtick-Zeichen verwenden

Wenn Sie innerhalb des Textes das Backtick-Zeichen (`) selbst als Quelltext ausgeben möchten, dann umschließen Sie es mit doppelten Backtick-Zeichen. Das folgende Beispiel zeigt dies.

``Verwenden des Backtick-Zeichens (`)``.

<p><code>Verwenden des Backtick-Zeichens (`)</code>.</p>

Möchten Sie innerhalb des Textes nur das Backtick-Zeichen (`) als Quelltext kenntlich machen, dann umschließen Sie es wieder mit jeweils zwei Backtick-Zeichen und einem Leerzeichen. Die Leerzeichen stehen dabei nach dem öffnenen doppelten Backtick-Zeichen und vor dem schließenden doppelten Backtick-Zeichen. Die beiden Leerzeichen sind dann im generierten HTML-Quelltext nicht enthalten. Das folgende Beispiel veranschaulicht dies.

Verwenden Sie das Backtick-Zeichen (`` ` ``).

<p>Verwenden Sie das Backtick-Zeichen (<code>`</code>).</p>

Automatische Zeichenumwandlung

Innerhalb der Backtick-Zeichen (`) werden spitze Klammern (<, >) und das &-Zeichen zu ihren HTML-Entities kodiert. Dadurch können Sie zum Beispiel sehr bequem HTML-Quelltext innerhab eines Textes notieren, so wie es das folgende Beispiel zeigt.

Das `<html>`-Tag leitet ein Dokument ein.
Durch das `&`-Zeichen werden URL-Parameter getrennt.

<p>Das <code>&lt;html&gt;</code>-Tag leitet ein Dokument ein.</p>
<p>Durch das <code>&amp;</code>-Zeichen werden URL-Parameter getrennt.</p>


Sie können innerhalb eines Quelltextbereichs auch HTML-Entities ausgeben, da auch hier das &-Zeichen umgewandelt/ kodiert wird. Das folgende Beispiel zeigt dies.

Das HTML-Entity `<` steht für das `<`-Zeichen.

<p>Das HTML-Entity <code>&amp;lt;</code> steht für das <code>&lt;</code>-Zeichen.</p>

Quelltext-Blöcke

Markdown bietet Ihnen eine einfache Möglichkeit, Quelltext-Blöcke kenntlich zu machen. Sie müssen dazu den Quelltext-Block mit mindestens vier Leerzeichen oder einem Tab einrücken. Das folgende Beispiel zeigt dies.

Das ist ein normaler Absatz.

    Das ist ein Quelltext-Block.

<p>Das ist ein normaler Absatz.</p>
<pre><code>Das ist ein Quelltext-Block.</code></pre>


Wenn Sie innerhalb des Quelltext-Blocks weitere Einrückungen vornehmen, dann wird bei der Umwandlung zu HTML jeweils eine Einrückungsebene (vier Leerzeichen oder ein Tab) entfernt. Das folgende Beispiel zeigt dies.

Das ist ein normaler Absatz.
    <html>
       <head>
             <meta charset=“utf-8“ />
       </head>
       <body>
       </body>
    </html>

<p>Das ist ein normaler Absatz.</p>
<pre><code>&lt;html&gt;
    &lt;head&gt;
      &lt;meta charset=“utf-8“ /&gt;
    &lt;/head&gt;
    &lt;body&gt;
    &lt;/body&gt;
&lt;/html&gt;
</code></pre>


Ein Quelltext-Block endet entweder bei der ersten Zeile, die nicht mehr eingerückt ist oder, wenn der Quelltext-Block am Ende des Dokuments steht, am Ende des Dokuments. Das folgende Beispiel zeigt dies.

Das ist der erste Absatz.

   <html>
      ...
   </html>

Das ist der zweite Absatz.

<p>Das ist der erste Absatz.</p>
<pre><code>&lt;html&gt;
    ...
&lt;/html&gt;
</code></pre>
<p>Das ist der zweite Absatz.</p>


Innerhalb von Quelltext-Blöcken wird Markdown-Syntax nicht verarbeitet/ interpretiert. So sind Sternchen dann auch einfach nur Sternchen - so wie es das nächste Beispiel zeigt.

Das ist der erste Absatz.

    Text können Sie mit Sternchen *betonen*.

Das ist der zweite Absatz.

<p>Das ist der erste Absatz.</p>
<pre><code>Text können Sie mit Sternchen *betonen*.
</code></pre>
<p>Das ist der zweite Absatz.</p>


Zitate

Markdown verwendet für die Formatierung von Zitaten das >-Zeichen.

Der folgende Text zeigt Ihnen die Auszeichnung von Zitaten mit Markdown. Einigen von ihnen wird dies sicher aus E-Mails bekannt vorkommen. Und genau aus diesem Zusammenhang entstand diese Syntax.

> Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
> sed diam nonumy eirmod tempor invidunt ut labore et dolore
> magna aliquyam erat, sed diam voluptua. At vero eos et accusam
> et justo duo dolores et ea rebum.

<blockquote>
  <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
sed diam nonumy eirmod tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam voluptua. At vero eos et accusam
et justo duo dolores et ea rebum.</p>
</blockquote>


Zitatebenen

Sie können, genauso wie bei E-Mails, auch mehrere Zitatebenen verwenden. Um eine weitere Zitatebene zu kennzeichnen, fügen sie einfach an den Zeilenanfang weitere >-Zeichen gefolgt von einem Leerzeichen ein. Um eine Ebene zurück zu kehren müssen Sie eine Leerzeile einfügen!
Das folgende Beispiel zeigt ihnen eine zweite Zitatebene für die zweite Zeile.

> Lorem ipsum dolor sit amet, consetetur sadipscing elitr,
>> sed diam nonumy eirmod tempor invidunt ut labore et dolore

> magna aliquyam erat, sed diam voluptua. At vero eos et accusam
> et justo duo dolores et ea rebum.

<blockquote>
	<p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr,</p>
	<blockquote>
		<p>sed diam nonumy eirmod tempor invidunt ut labore et dolore</p>
	</blockquote>
	<p>magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum.</p>
</blockquote>


Markdown in Zitaten

Zitate können natürlich auch selbst andere Markdown-Auszeichnungen enthalten. Der folgende Text zeigt ihnen dazu beispielhaft, wie man innerhalb eines Zitats eine Überschrift (ersten Grades) notiert.

> # Lorem ipsum
> sed diam nonumy eirmod tempor invidunt ut labore et dolore
> magna aliquyam erat, sed diam voluptua. At vero eos et accusam
> et justo duo dolores et ea rebum.

<blockquote>
  <h1 id=“lorem-ipsum“>Lorem ipsum</h1>
  <p>sed diam nonumy eirmod tempor invidunt ut labore et dolore
magna aliquyam erat, sed diam voluptua. At vero eos et accusam
et justo duo dolores et ea rebum.</p>
</blockquote>


Horizontale Linien

Um mit Markdown eine horizontale Linie (<hr>-Tag) auzugeben, schreibt man drei oder mehr Bindestriche, Unterstriche oder Sternchen in einer Zeile. In dieser Zeile dürfen sonst keine anderen Zeichen stehen. Zwischen den Zeichen dürfen bis zu zwei Leerzeichen stehen.

---
----------
- - - - - - - - - -
***
* * *
* * * * * * * * * *
___
__________
_ _ _ _ _ _ _ _ _ _

Achtung: Wenn sie als Zeichen den Bindestrich verwenden, dann darf in der Zeile davor nichts stehen, da dies sonst als Überschrift (siehe Überschriften) interpretiert werden würde.

Automatische Maskierung

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 für benannte HTML-Zeichen (Entities) verwendet. Wenn diese Zeichen in HTML-Dokumenten dargestellt werden sollen (d.h. nicht als HTML-Entity), müssen sie auch entsprechend maskiert werden, also als &lt; und &amp;.

Das kaufmännische Und ist besonders unpraktisch für Web-Entwickler. Will man über „AT&T“ schreiben, muss man „AT&amp;T“ schreiben. Das kaufmännische Und muss sogar in URLs maskiert werden. In einem Link zur Seite

http://images.google.com/images?num=30&q=larry+bird

muss die URL wie folgt kodiert werden:

http://images.google.com/images?num=30&amp;q=larry+bird

Dies wohl einer der häufigsten Fehler bei der Validierung von ansonsten wohlgeformten HTML-Dokumenten.Markdown erlaubt es, diese Zeichen ganz normal zu benutzen - es regelt die Kodierung. Wenn ein Kaufmanns-Und allerdings in einem Entity verwendet wird, wird es nicht kodiert. Wenn man also zum Beispiel ein Copyright-Symbol eingeben will, kann man einfach

&copy

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 von HTML in Markdown (Im Gegensatz zu reinem HTML, wo dies meist ein Alptraum ist, jedes < und & zu kodieren).

Backslah 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