Was ist Markdown und warum ist es überall?
Markdown ist eine leichtgewichtige Auszeichnungssprache, die John Gruber 2004 veröffentlichte. Die Idee war einfach: ein Textformat, das sowohl als Quelltext lesbar ist als auch in HTML konvertiert werden kann. Heute ist Markdown der De-facto-Standard für technische Dokumentation, README-Dateien, Chat-Nachrichten und statische Websites.
Der Grund für diese Verbreitung ist die niedrige Einstiegshürde. Du brauchst keinen speziellen Editor — jeder Texteditor reicht. Die Syntax ist intuitiv genug, dass du sie innerhalb von zehn Minuten produktiv einsetzen kannst, und mächtig genug, dass sie für Bücher und komplexe Dokumentationen taugt.
Allerdings gibt es nicht „das eine Markdown". CommonMark standardisiert die Grundlagen, aber Plattformen wie GitHub (GFM), Obsidian und MDX erweitern die Syntax um eigene Features. In diesem Guide behandeln wir die Grundlagen, die überall funktionieren, und markieren plattformspezifische Erweiterungen deutlich.
Überschriften, Absätze und Zeilenumbrüche
Überschriften werden mit # erstellt — ein # für H1, zwei ## für H2 und so weiter bis ###### für H6. Die meisten Style-Guides empfehlen, nur ein H1 pro Dokument zu verwenden und die Hierarchie nicht zu überspringen (also kein H4 direkt nach einem H2).
Absätze werden durch eine Leerzeile getrennt. Ein einfacher Zeilenumbruch im Quelltext erzeugt keinen neuen Absatz — der Text wird zusammengefügt. Wenn du einen harten Zeilenumbruch innerhalb eines Absatzes willst, setze zwei Leerzeichen am Zeilenende oder verwende <br>.
Horizontale Linien erstellst du mit drei oder mehr Bindestrichen (---), Sternchen (***) oder Unterstrichen (___) auf einer eigenen Zeile. Sie eignen sich gut zum visuellen Trennen von Abschnitten, aber in den meisten Fällen ist eine neue Überschrift die bessere Wahl für die Dokumentstruktur.
# Hauptüberschrift (H1)
## Abschnitt (H2)
### Unterabschnitt (H3)
Ein normaler Absatz. Dieser Satz
steht im Quelltext auf einer neuen Zeile,
wird aber als ein Absatz gerendert.
Zwei Leerzeichen am Ende erzeugen
einen harten Zeilenumbruch.
---Textformatierung: Fett, Kursiv, Code
Kursiver Text wird mit einem Sternchen oder Unterstrich umschlossen: *kursiv* oder _kursiv_. Fetter Text braucht zwei: **fett** oder __fett__. Für fett und kursiv kombiniert verwendest du drei: ***beides***. Die meisten Linter bevorzugen Sternchen über Unterstriche, weil Unterstriche in Wörtern wie file_name Probleme verursachen können.
Inline-Code wird mit Backticks markiert: `code`. Wenn dein Code selbst Backticks enthält, verwende doppelte Backticks: ``code mit ` drin``. Für Code-Blöcke nutzt du drei Backticks mit optionaler Sprachangabe für Syntax-Highlighting.
Durchgestrichener Text ist kein CommonMark-Standard, aber GFM und die meisten Plattformen unterstützen ~~durchgestrichen~~. Obsidian bietet zusätzlich ==markiert== für Hervorhebungen. Prüfe immer, welche Erweiterungen deine Zielplattform unterstützt.
Ein häufiger Fehler: Formatierungszeichen ohne Leerzeichen an den richtigen Stellen. **fett** funktioniert, aber ** fett ** (mit Leerzeichen innen) wird auf vielen Parsern nicht konvertiert. Halte die Marker direkt am Text.
*kursiv* und **fett** und ***beides***
~~durchgestrichen~~ (GFM-Erweiterung)
Inline-Code: `const x = 42;`
```typescript
// Code-Block mit Syntax-Highlighting
function grüße(name: string): string {
return `Hallo, ${name}!`;
}
```Listen: Geordnet, ungeordnet und verschachtelt
Ungeordnete Listen beginnen mit -, * oder +. Die meisten Projekte einigen sich auf einen Stil — Bindestriche sind am weitesten verbreitet. Geordnete Listen beginnen mit einer Zahl gefolgt von einem Punkt: 1. Erstes Element. Die tatsächliche Nummer spielt keine Rolle — der Parser nummeriert automatisch sequentiell.
Verschachtelung funktioniert durch Einrückung. In CommonMark brauchst du eine Einrückung, die bis unter den Inhalt des übergeordneten Listenelements reicht (typischerweise 2-4 Leerzeichen). GFM ist toleranter, aber für maximale Kompatibilität verwende konsistent 2 oder 4 Leerzeichen.
Aufgabenlisten (Task Lists) sind eine GFM-Erweiterung: - [ ] Offene Aufgabe und - [x] Erledigte Aufgabe. Sie werden in GitHub Issues und Pull Requests als interaktive Checkboxen gerendert. In statischen Sites brauchst du einen Plugin für die Checkbox-Darstellung.
Achtung bei Absätzen in Listen: Wenn du nach einem Listenelement eine Leerzeile einfügst und den nächsten Text einrückst, wird er als Teil des Listenelements interpretiert. Das ist nützlich für mehrzeilige Listeneinträge, aber verwirrend wenn es unbeabsichtigt passiert.
- Erster Punkt
- Zweiter Punkt
- Verschachtelter Punkt
- Noch einer
1. Schritt eins
2. Schritt zwei
3. Schritt drei
- [x] Tests geschrieben
- [x] Code reviewed
- [ ] Deployment vorbereitenLinks, Bilder und Referenzen
Inline-Links folgen dem Muster [Linktext](URL "optionaler Titel"). Der Titel erscheint als Tooltip beim Hovern. Für lange URLs oder wiederholte Links sind Referenz-Links übersichtlicher: [Linktext][ref] mit [ref]: URL am Ende des Dokuments.
Bilder verwenden die gleiche Syntax mit einem vorangestellten Ausrufezeichen: . Der Alt-Text ist für Barrierefreiheit essenziell — beschreibe was das Bild zeigt, nicht wie es aussieht. Markdown selbst bietet keine Möglichkeit, Bildgrößen zu definieren; dafür brauchst du HTML oder plattformspezifische Erweiterungen.
Automatische Links funktionieren in GFM: URLs und E-Mail-Adressen werden automatisch verlinkt. In CommonMark musst du sie in spitze Klammern setzen: <https://example.com>. Für interne Links in Dokumentation verwende relative Pfade — das macht die Docs portabel zwischen Hosting-Plattformen.
Fußnoten sind in vielen Markdown-Varianten verfügbar: Text mit Fußnote[^1] und [^1]: Erklärung am Ende. GitHub unterstützt sie seit 2021. Sie eignen sich für Quellenangaben oder ergänzende Informationen, die den Lesefluss nicht unterbrechen sollen.
<!-- Inline-Link -->
[Unsere Tools](https://example.com/tools "Toolbox öffnen")
<!-- Referenz-Link -->
[Markdown-Spezifikation][commonmark]
[commonmark]: https://spec.commonmark.org/
<!-- Bild mit Alt-Text -->
<!-- Fußnote -->
Markdown wurde 2004 veröffentlicht[^1].
[^1]: Zusammen mit dem ersten Perl-Skript als Konverter.Tabellen und erweiterte Blöcke
Tabellen gehören nicht zu CommonMark, sind aber in GFM und praktisch allen modernen Markdown-Implementierungen verfügbar. Die Syntax verwendet Pipes (|) als Spaltentrennzeichen und eine Trennlinie mit Bindestrichen. Die Ausrichtung steuerst du mit Doppelpunkten in der Trennlinie.
Für komplexe Tabellen mit Colspan oder verschachtelten Elementen stößt Markdown an seine Grenzen. In solchen Fällen ist eingebettetes HTML die pragmatische Lösung. Die meisten Markdown-Parser erlauben rohes HTML — nutze es sparsam, aber ohne schlechtes Gewissen wenn nötig.
Blockzitate (Blockquotes) beginnen mit >. Sie können verschachtelt werden (>> für ein Zitat im Zitat) und andere Markdown-Elemente enthalten. In vielen Dokumentations-Setups werden sie für Hinweise (Notes, Warnings) verwendet — GitHub unterstützt seit 2022 spezielle Admonitions wie > [!NOTE] und > [!WARNING].
Zusammenklappbare Abschnitte (<details> und <summary>) sind technisch HTML, aber in GitHub-Markdown so verbreitet, dass sie praktisch zum Standard gehören. Sie sind ideal für lange Fehlermeldungen, optionale Details oder FAQ-Abschnitte in READMEs.
| Funktion | CommonMark | GFM | Obsidian |
| -------------- | :--------: | :--: | :------: |
| Tabellen | ❌ | ✅ | ✅ |
| Fußnoten | ❌ | ✅ | ✅ |
| Task Lists | ❌ | ✅ | ✅ |
| Wikilinks | ❌ | ❌ | ✅ |
> [!WARNING]
> Diese Syntax funktioniert nur auf GitHub.
<details>
<summary>Mehr Details anzeigen</summary>
Versteckter Inhalt hier.
</details>Markdown-Linting und Best Practices
markdownlint (als CLI oder VS-Code-Extension) prüft deine Dateien gegen konfigurierbare Regeln. Die wichtigsten: konsistente Überschriftenstile, keine Trailing Spaces, eine Leerzeile vor und nach Überschriften, und kein HTML wenn Markdown ausreicht. Die Konfiguration erfolgt über .markdownlint.json oder .markdownlint-cli2.yaml.
Für Projekte mit vielen Autoren hilft ein .editorconfig mit Einstellungen für .md-Dateien: trim_trailing_whitespace = false (wegen der harten Zeilenumbrüche durch zwei Leerzeichen), insert_final_newline = true und indent_style = space. Das reduziert überflüssige Diff-Noise in Pull Requests.
Linkvalidierung ist in großen Dokumentationsprojekten kritisch. Tools wie markdown-link-check oder lychee prüfen alle Links in deinen Dateien — sowohl interne Referenzen als auch externe URLs. Integriere sie in deine CI-Pipeline, damit tote Links nicht unbemerkt bleiben.
Remark ist das programmierbare Markdown-Ökosystem: Parser, Transformer und Serializer als separate Module. Damit kannst du automatische Transformationen bauen — etwa das Einfügen von Inhaltsverzeichnissen, das Normalisieren von Link-Stilen oder das Extrahieren von Frontmatter für statische Sites.
// .markdownlint.json — Beispielkonfiguration
{
"MD013": false,
"MD033": {
"allowed_elements": ["details", "summary", "br"]
},
"MD024": {
"siblings_only": true
},
"MD041": true
}Markdown in der Praxis: Plattformunterschiede
GitHub Flavored Markdown (GFM) ist der am weitesten verbreitete Dialekt. Es erweitert CommonMark um Tabellen, Task Lists, Autolinks, Strikethrough und Fußnoten. Die offizielle GFM-Spezifikation wird von GitHub gepflegt und ist unter github.github.com/gfm/ dokumentiert.
Obsidian verwendet einen eigenen Parser mit Wikilinks ([[Seitenname]]), Callouts, eingebetteten Dateien (![[datei.pdf]]) und mathematischen Formeln via MathJax. Wenn du Obsidian-Markdown in andere Systeme migrierst, brauchst du Konvertierungstools für diese proprietären Erweiterungen.
MDX kombiniert Markdown mit JSX-Komponenten. Das ist ideal für interaktive Dokumentation (Docusaurus, Next.js-Blogs), bringt aber Build-Komplexität mit. Jede MDX-Datei wird zu einer React-Komponente kompiliert, was bedeutet, dass Syntaxfehler erst beim Build auffallen.
Für maximale Portabilität schreibe CommonMark mit minimalen Erweiterungen. Verwende GFM-Tabellen und Fußnoten (breite Unterstützung), aber vermeide plattformspezifische Features wie Wikilinks oder Callouts, es sei denn du bist an eine Plattform gebunden. Unser Markdown-Editor unterstützt CommonMark plus GFM-Erweiterungen und zeigt dir eine Live-Vorschau deines Dokuments.