Markdown in 10 Minuten: Die wichtigsten Befehle, die du brauchst

Markdown ist die wahrscheinlich produktivste Sprache, die du in deinem Leben lernen wirst -- ueberschaubar in zwanzig Regeln, brauchbar fuer den Rest deiner Karriere. README-Dateien auf GitHub, Issues in GitLab, Nachrichten in Discord, Dokumentationen mit MkDocs, Blog-Posts in Hugo, Notizen in Obsidian -- ueberall ist Markdown der gemeinsame Nenner. Dieser Artikel zeigt jede wichtige Regel mit einem Mini-Beispiel, erklaert die Unterschiede zwischen CommonMark und GitHub Flavored Markdown und raeumt mit den klassischen Stolperfallen auf, ueber die jeder einmal stolpert.

Eine kurze Geschichte (zwei Minuten)

Markdown wurde 2004 von John Gruber zusammen mit Aaron Swartz erfunden. Grubers Designziel war kompromisslos: die Quelle soll wie eine sauber formatierte E-Mail aussehen, nicht wie Code. Es soll lesbar bleiben, selbst wenn niemand sie je in HTML uebersetzt. Diese Philosophie erklaert die scheinbar willkuerlichen Entscheidungen -- warum Listen mit einem einfachen Bindestrich beginnen statt mit einem Tag, warum eine leere Zeile einen Absatz definiert, warum eine Ueberschrift mit einem Doppelkreuz markiert wird.

Das Problem: Grubers Originalspezifikation war voller Mehrdeutigkeiten. Jeder Parser interpretierte Kanten anders, was zu fragmentierten Implementierungen fuehrte. 2014 starteten Jeff Atwood, John MacFarlane und andere CommonMark, einen praezisen, getesteten Standard mit ueber 600 Testfaellen. Daneben entstand GitHub Flavored Markdown (GFM) als formelle Erweiterung mit Tabellen, Task-Listen, Strikethrough und Autolinks. Heute folgen die meisten Tools entweder CommonMark oder GFM -- oder beidem.

Ueberschriften

Ueberschriften gibt es in sechs Stufen, markiert durch ein bis sechs Doppelkreuze am Zeilenanfang, gefolgt von einem Leerzeichen. CommonMark akzeptiert auch die alte Setext-Notation (Unterstreichung mit Gleichheitszeichen fuer H1 oder Bindestrichen fuer H2), aber die ATX-Variante (mit #) ist klarer und in der Praxis ueberall durchgesetzt.

# H1 Ueberschrift
## H2 Ueberschrift
### H3 Ueberschrift
#### H4 Ueberschrift
##### H5 Ueberschrift
###### H6 Ueberschrift

Wichtige Regel: vor und nach jeder Ueberschrift gehoert eine leere Zeile -- viele Parser akzeptieren es auch ohne, aber konsistente Lesbarkeit gewinnt. Mehr als sechs Doppelkreuze sind keine Ueberschrift mehr, sondern werden als Text gerendert.

Hervorhebungen: kursiv, fett, durchgestrichen

Markdown nutzt Sternchen oder Unterstriche fuer Hervorhebungen. Ein Zeichen drumherum macht kursiv, zwei machen fett, drei machen fett-kursiv. GFM ergaenzt Strikethrough mit doppelten Tilden. Vorsicht bei Unterstrichen innerhalb von Woertern -- snake_case_variable wuerde sonst zur Haelfte kursiv. CommonMark schuetzt diesen Fall heuristisch, aeltere Parser nicht.

*kursiv* oder _kursiv_
**fett** oder __fett__
***fett-kursiv***
~~durchgestrichen~~ (GFM)

Listen, geordnet und ungeordnet

Ungeordnete Listen beginnen mit -, * oder + gefolgt von einem Leerzeichen. Geordnete Listen beginnen mit einer Zahl und einem Punkt. Wichtig: der Renderer numeriert ohnehin neu -- du kannst alle Eintraege als 1. schreiben, das Ergebnis ist eine korrekt numerierte Liste 1, 2, 3, 4. Verschachtelung erfolgt durch Einrueckung mit zwei oder vier Leerzeichen.

- erster Eintrag
- zweiter Eintrag
  - verschachtelt
  - noch ein verschachtelter
- dritter Eintrag

1. Schritt eins
1. Schritt zwei
1. Schritt drei

Klassischer Bug: vor einer Liste fehlt die Leerzeile zum vorherigen Absatz -- der Parser behandelt die Liste dann als Fortsetzung des Absatzes und der Bindestrich erscheint als Text. Immer eine leere Zeile vor der Liste lassen.

Links und Bilder

Links bestehen aus dem Linktext in eckigen Klammern, gefolgt von der URL in runden Klammern. Optional kann ein Title in Anfuehrungszeichen folgen, der als Tooltip im Browser angezeigt wird. Reference-Style-Links trennen Text und URL -- praktisch fuer lange Texte, in denen dieselbe URL mehrmals vorkommt. Autolinks setzen eine URL einfach in spitze Klammern und der Parser macht daraus einen anklickbaren Link. Bilder funktionieren wie Links mit einem Ausrufezeichen davor und dem Alt-Text in den eckigen Klammern.

[CalcSI](https://calcsi.com "Online-Tools")

[reference][1]

[1]: https://example.com

<https://autolink.example>

![Alt-Text](https://example.com/bild.png)

Tipp fuer SEO und Barrierefreiheit: Alt-Texte sind nicht optional. Screen-Reader lesen sie vor, Suchmaschinen lesen sie als Inhaltsbeschreibung. Ein leerer Alt-Text (![](url)) ist nur fuer rein dekorative Bilder gerechtfertigt.

Code: inline und Bloecke

Inline-Code wird in Backticks gesetzt -- ideal fuer Funktionsnamen, Variablen oder kurze Befehle im Fließtext. Code-Bloecke gehen ueber mehrere Zeilen und werden mit drei Backticks am Anfang und Ende eingeschlossen. Eine optionale Sprachangabe nach den oeffnenden Backticks aktiviert Syntax-Highlighting in den meisten Renderern (GitHub, Prism, Highlight.js). Wenn der eigene Code selbst Backticks enthaelt, einfach vier oder mehr Backticks um den Block setzen.

Inline: `let x = 42;`

Block mit Sprachangabe:

```javascript
function greet(name) {
  return `Hallo, ${name}`;
}
```

Alternative: vier Leerzeichen Einrueckung definieren ebenfalls einen Codeblock (klassische Notation), aber gefenced Blocks mit Backticks sind ueberall der Standard, weil sie auch Sprachangaben erlauben.

Tabellen (GFM)

Tabellen sind nicht Teil von CommonMark, aber GitHub Flavored Markdown definiert sie sauber -- und alle relevanten Tools unterstuetzen das. Zellen werden mit senkrechten Strichen getrennt, die zweite Zeile aus Bindestrichen markiert die Headerzeile. Ausrichtung wird durch Doppelpunkte gesteuert: :--- links, :---: zentriert, ---: rechts.

| Format | Geschwindigkeit | Lesbarkeit |
|:-------|:---------------:|-----------:|
| JSON   | sehr hoch       |     gering |
| YAML   | mittel          |       hoch |
| TOML   | hoch            |       hoch |

Die Spalten in der Quelle muessen nicht ausgerichtet sein -- der Renderer kuemmert sich darum -- aber sauber ausgerichteter Markdown-Source liest sich auch unrendiert wie eine Tabelle. Genau dafuer wurde Markdown erfunden.

Blockquotes, Trennlinien, Tasks, Fußnoten

Fuenf Bauteile, die im Alltag dazwischen liegen und oft uebersehen werden:

• Blockquotes: mit > am Zeilenanfang. Mehrere Ebenen mit >>, >>>. Im Quote kann beliebiger Markdown stehen, inklusive Listen und Codebloecke.
• Trennlinie: drei oder mehr Bindestriche, Sternchen oder Unterstriche in einer eigenen Zeile, mit leeren Zeilen drumherum. Rendert als <hr>.
• Task-Listen (GFM): - [ ] fuer offen, - [x] fuer erledigt. Perfekt fuer Issue-Templates, TODO-Listen, Release-Checklisten. Auf GitHub klickbar.
• Fußnoten (GFM-Extension): im Text [^1], irgendwo darunter [^1]: erklaerender Text. Renderer sammelt sie am Ende des Dokuments.
• Escaping: ein Backslash schuetzt jedes Markdown-Sonderzeichen. \*kein kursiv\* rendert woertlich. Praktisch fuer Dokumentation, in der Sternchen Text bleiben sollen.

> Das ist ein Zitat.
>
> > Verschachtelt.

---

- [x] Markdown gelernt
- [ ] Eigenes Cheatsheet schreiben

Dieser Satz hat eine Fußnote[^1].

[^1]: Hier steht die Erklaerung.

Klassische Stolperfallen

Drei Fehler, die fast jeder einmal macht. Erstens: Zeilenumbruch ist nicht intuitiv. Eine einzelne neue Zeile im Source landet im selben Absatz im Ausgabedokument. Wer einen echten Umbruch (<br>) will, schreibt zwei Leerzeichen am Zeilenende oder eine Leerzeile. Auf GitHub und in vielen Chat-Apps wird die einfache neue Zeile dagegen interpretiert -- das ist eine GFM-Abweichung vom Standard, gemacht weil sie sich fuer Chat-Eingaben natuerlicher anfuehlt.

Zweitens: Listen brauchen vor sich eine Leerzeile, sonst werden sie zu Absatztext. Drittens: Numerierte Listen starten nicht beim erwarteten Wert, wenn man 3. als ersten Eintrag schreibt -- in CommonMark beginnt die Liste tatsaechlich bei 3, in vielen aelteren Parsern wird stillschweigend bei 1 begonnen. Wer das ausnutzen will, sollte beim eigenen Renderer pruefen. Sicheres Default: immer mit 1. beginnen.

Wo Markdown heute lebt

Markdown ist die Default-Sprache fuer technische Schrift im Web. GitHub und GitLab nutzen es fuer READMEs, Issues, Pull Requests und Wikis. Discord rendert eine reduzierte Variante in Nachrichten, Slack ein eigenes Subset. Statische Site-Generatoren -- Hugo (Go), Jekyll (Ruby), Astro und Next.js (JavaScript) -- nehmen Markdown als Quellformat und produzieren HTML. Dokumentationssysteme wie MkDocs, Docusaurus, Sphinx (via MyST) und VitePress folgen demselben Muster.

Auch jenseits des Webs hat Markdown sich durchgesetzt: Obsidian, Notion (mit Erweiterungen), Bear, iA Writer, Typora speichern Notizen als Markdown-Dateien. Vorteil: dein Text gehoert dir und ist auch in zehn Jahren noch lesbar, egal welches Tool ueberlebt. Wer eine schnelle Vorschau ohne Editor braucht, kann den Markdown-zu-HTML-Konverter auf CalcSI nutzen -- Input links, gerendertes HTML rechts, alles im Browser.

Haeufige Fragen

Was ist der Unterschied zwischen Markdown und MDX?

MDX ist Markdown plus JSX. Du kannst React-Komponenten direkt im Markdown-Quelltext einsetzen, etwa <Chart data={...} /> mitten in einem Absatz. Beliebt in modernen Doku-Systemen wie Docusaurus und Next.js, weil interaktive Demos und Standardtext im selben Dokument leben. Nachteil: MDX-Dateien sind nicht mehr in jedem Markdown-Renderer darstellbar -- ohne JSX-Toolchain hast du nur Source. Fuer reine Dokumentation und Blogs reicht Standard-Markdown oder GFM -- MDX nur dann, wenn du Komponenten brauchst.

Wie sicher ist es, beliebigen Markdown nach HTML zu rendern?

Markdown selbst erlaubt rohes HTML -- ein Angreifer kann einen <script>-Tag direkt in Markdown schreiben und der Default-Renderer wuerde ihn ausgeben. Jede Anwendung, die Nutzer-Markdown rendert (Forum, Kommentare, CMS), muss den HTML-Output mit einer Bibliothek wie DOMPurify oder einer serverseitigen Allowlist sanitizieren. GitHub, GitLab und CalcSI machen das alle -- es ist eine harte Sicherheitsregel, keine Komfortfrage. Wer roh rendert, hat eine XSS-Luecke.

Kann ich Diagramme in Markdown einbetten?

Auf GitHub und in vielen modernen Renderern (Obsidian, GitLab, MkDocs mit Plugin): ja, ueber Mermaid in einem Codeblock mit Sprachangabe mermaid. Du schreibst dort die Diagramm-Definition (Flowchart, Sequenzdiagramm, Class-Diagramm), und der Renderer wandelt das in SVG. Vorteil: Diagramme leben im selben Repo wie der Code und werden versioniert. Nachteil: nicht jeder Markdown-Parser kennt Mermaid -- fuer maximale Portabilitaet bleibt nur ein eingebettetes Bild.