Markdown: Vollständige Syntaxreferenz für Autoren und Entwickler

Markdown ist überall. Es ist das Standard-Schreibformat auf GitHub, das Rückgrat der meisten Static-Site-Generatoren, die native Sprache von Tools wie Obsidian und Notion und das Format, zu dem Entwickler greifen, wenn sie READMEs, Dokumentationen und technische Notizen schreiben. Obwohl allgegenwärtig, lernen viele Autoren und Entwickler nur die Grundlagen — Fett, Kursiv und ein paar Überschriftsebenen — und verpassen die Funktionen, die Markdown für strukturiertes Schreiben wirklich leistungsfähig machen.

Sie können Markdown sofort schreiben und in der Vorschau anzeigen mit dem BrowseryTools Markdown-Editor — kostenlos, ohne Anmeldung, alles läuft in Ihrem Browser.

Wer Markdown erstellt hat und warum

Markdown wurde von John Gruber in Zusammenarbeit mit Aaron Swartz erstellt und 2004 veröffentlicht. Grubers erklärtes Ziel war es, ein Klartext-Schreibformat zu schaffen, das vor jeder Darstellung lesbar ist — also im Rohformat — und das sauber in gültiges HTML konvertiert. Der Name ist ein Wortspiel auf „Markup Language" (HTML ist HyperText Markup Language), das Konzept umkehrend: Statt Syntax hinzuzufügen, um Formatierung zu steuern, verwendet Markdown die natürlichen Interpunktionsgewohnheiten, die Menschen bereits in Klartext-E-Mails entwickelt hatten.

Die Motivation war praktisch. HTML ist ausführlich und beim Schreiben ablenkend. Ein Satz wie <p>Das ist <strong>wichtig</strong>er Text.</p> erfordert erheblichen mentalen Aufwand im Vergleich zu Das ist **wichtiger** Text. Gruber wollte, dass Blogger und Autoren sich auf Wörter konzentrieren, nicht auf Tags. Die ursprüngliche Markdown-Spezifikation war ein Perl-Skript, das Klartext-Markdown-Dateien in HTML umwandelte.

Grundlegende Syntax

Die Kern-Markdown-Syntax deckt alles ab, was die meisten Autoren für strukturierte Dokumente benötigen.

Überschriften

Verwenden Sie Rautezeichen, um Überschriften zu erstellen. Ein Rautezeichen für H1, zwei für H2, bis zu sechs für H6. Die meisten Stilhandbücher empfehlen nur ein H1 pro Dokument (typischerweise der Titel) und die Verwendung von H2–H4 für die Inhaltshierarchie.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Betonung und Hervorhebung

*italic* or _italic_
**bold** or __bold__
***bold and italic***
~~strikethrough~~

Links und Bilder

[Link text](https://example.com)
[Link with title](https://example.com "Page title")
![Alt text](image.png)
![Alt text](image.png "Image title")

Listen

Ungeordnete Listen verwenden Bindestriche, Sternchen oder Pluszeichen. Geordnete Listen verwenden Zahlen gefolgt von Punkten. Eingerückte Elemente (2 oder 4 Leerzeichen) erzeugen verschachtelte Listen.

- Unordered item
- Another item
  - Nested item

1. First
2. Second
3. Third

Code

Inline-Code verwendet einfache Backticks. Code-Blöcke mit Begrenzern verwenden dreifache Backticks mit einem optionalen Sprachbezeichner für Syntax-Hervorhebung.

Use `console.log()` for debugging.

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

Blockzitate

> This is a blockquote.
> It can span multiple lines.
>
> > Nested blockquotes work too.

Horizontale Trennlinien

Drei oder mehr Bindestriche, Sternchen oder Unterstriche allein auf einer Zeile erzeugen eine horizontale Trennlinie. --- ist die gebräuchlichste Konvention.

Erweiterte Syntax

Die ursprüngliche Markdown-Spezifikation ließ einige Funktionen aus, die Autoren häufig benötigen. Die erweiterte Syntax, die von den meisten modernen Prozessoren unterstützt wird, fügt diese Möglichkeiten hinzu.

Tabellen

| Column 1  | Column 2  | Column 3  |
|-----------|:---------:|----------:|
| Left      | Center    | Right     |
| aligned   | aligned   | aligned   |

Die Doppelpunkt-Position in der Trennzeile steuert die Ausrichtung: links (Standard), mittig (Doppelpunkte auf beiden Seiten) oder rechts (Doppelpunkt rechts).

Aufgabenlisten

- [x] Write first draft
- [x] Peer review
- [ ] Final edits
- [ ] Publish

Fußnoten

Here is a claim that needs a citation.[^1]

[^1]: The supporting source or explanation goes here.

Markdown-Varianten: CommonMark, GFM und MDX

Die ursprüngliche Markdown-Spezifikation enthielt Mehrdeutigkeiten — Stellen, an denen Prozessoren unterschiedliche Entscheidungen über Grenzfälle trafen. Das führte zu inkompatiblen Implementierungen in verschiedenen Tools. Es entstanden mehrere Standardisierungsbemühungen, um dies zu lösen.

• CommonMark — eine strenge Spezifikation, die jede Mehrdeutigkeit in der ursprünglichen Markdown-Spezifikation mit einer formalen Test-Suite auflöst. Von Discourse, Reddit, Stack Overflow und vielen anderen übernommen. Die interoperabelste Variante.
• GitHub Flavored Markdown (GFM) — GitHubs Erweiterung von CommonMark, die Tabellen, Aufgabenlisten, Durchstreichen, Autolinks und wörtliche URLs hinzufügt. Wenn Sie README-Dateien oder GitHub-Kommentare schreiben, verwenden Sie GFM.
• MDX — Markdown erweitert um JSX-Komponenten-Unterstützung, intensiv verwendet in React-basierten Dokumentationsseiten (Next.js Docs, Docusaurus, Astro). Ermöglicht das direkte Importieren und Einbetten von React-Komponenten in Markdown-Dateien.
• MultiMarkdown / Pandoc Markdown — funktionsreiche Erweiterungen für akademisches Schreiben mit Unterstützung für Zitate, mathematische Formeln (LaTeX) und komplexe Tabellenformatierung.

Wo Markdown verwendet wird

• GitHub und GitLab — README-Dateien, Issues, Pull Requests, Wikis und Kommentare rendern alle Markdown
• Notion — unterstützt Markdown-Import/-Export und eine Teilmenge von Markdown-Shortcuts für Inline-Formatierung
• Obsidian — eine Wissensmanagement-App, die vollständig auf Markdown-Dateien mit Wikilink-Erweiterungen aufgebaut ist
• Static-Site-Generatoren — Jekyll, Hugo, Gatsby, Astro und Next.js verwenden alle Markdown oder MDX als Standard-Inhaltsformat
• Dokumentationsplattformen — ReadTheDocs, GitBook und Docusaurus sind um Markdown herum aufgebaut
• Chat-Plattformen — Slack, Discord und Teams unterstützen Teilmengen von Markdown für die Nachrichtenformatierung
• E-Mail-Clients — einige Clients (Superhuman, HEY) unterstützen Markdown-Eingabe

Markdown vs. Rich-Text-Editoren

Rich-Text-Editoren (WYSIWYG — What You See Is What You Get) wie Google Docs, Microsoft Word oder der eingebaute Editor von Contentful zeigen formatierte Ausgabe beim Tippen. Markdown zeigt den Rohtext. Die Kompromisse sind real.

• Markdown-Vorteile — Klartextdateien, funktioniert in jedem Editor, mit Git versionierbar, keine Anbieterabhängigkeit, schneller tastaturzentrierter Workflow
• Rich-Text-Vorteile — sofort visuell, keine Syntax zu lernen, einfacher für nicht-technische Mitarbeiter, besser für komplexe Formatierung (Fußnoten, Kommentare, Änderungsverfolgung)

Für technisches Schreiben, Entwickler-Dokumentation und persönliches Wissensmanagement macht Markdowns Portabilität und Versionskontroll-Kompatibilität es zur besseren Wahl. Für kollaborative Geschäftsdokumente oder Inhalte mit komplexen Formatierungsanforderungen ist ein Rich-Text-Editor oft praktischer.

Häufige Markdown-Fehler

• Fehlende Leerzeilen — die meisten Block-Elemente (Überschriften, Listen, Code-Blöcke) benötigen eine Leerzeile davor und danach, um korrekt gerendert zu werden
• Leerzeichen nach Rautezeichen — ##Überschrift ohne Leerzeichen nach den Rautezeichen ist bei den meisten Prozessoren keine Überschrift
• Inkonsistente Listenmarkierungen — das Mischen von - und * in derselben Liste kann bei einigen Prozessoren unerwartete Ergebnisse erzeugen
• Vergessen, Sonderzeichen zu maskieren — Sternchen, Unterstriche und Backticks innerhalb von Text benötigen einen Backslash-Escape, wenn sie wörtlich dargestellt werden sollen
• Annahme, dass erweiterte Syntax universell ist — Tabellen und Aufgabenlisten sind GFM-Funktionen, die nicht von allen Prozessoren unterstützt werden; prüfen Sie Ihre Zielumgebung

Der BrowseryTools Markdown-Editor bietet eine Live-Vorschau, damit Sie Darstellungsprobleme sofort beim Schreiben erkennen können, ohne Text in ein anderes Tool kopieren zu müssen. Fügen Sie Ihr Markdown ein und sehen Sie die gerenderte HTML-Ausgabe nebeneinander.