Markdown-Leitfaden für Autoren und Entwickler
Markdown-Syntax von den Grundlagen bis zu fortgeschrittenen Funktionen meistern – Tabellen, Code-Blöcke, Aufgabenlisten und die Unterschiede zwischen Markdown-Varianten.
Markdown ist so etwas wie das universelle Schreibformat des Internets. Es wird in GitHub-READMEs, Notion-Dokumenten, Slack-Nachrichten, Dokumentationsseiten, Blogbeiträgen und Entwicklernotizen verwendet. Einmal gelernt, setzt du es überall ein – für den Rest deiner Karriere.
Was ist Markdown?
Markdown ist eine leichtgewichtige Auszeichnungssprache, die John Gruber im Jahr 2004 entwickelt hat. Der Grundgedanke: in Klartext mit einfachen Satzzeichenkonventionen schreiben, der dann zu sauber formatiertem HTML gerendert wird.
This **bold text** and *italic text* render instantly.
Gerendert ergibt das: This bold text and italic text render instantly.
Der Rohtext ist dabei auch vor dem Rendern noch problemlos lesbar.
Grundlegende Syntax
Überschriften
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
Überschriften dienen dazu, eine Dokumenthierarchie zu erzeugen. # H1 ist typischerweise der Seitentitel – verwende ihn nur einmal pro Dokument.
Hervorhebungen
**bold text**
*italic text*
***bold and italic***
~~strikethrough~~
Listen
Unordered list:
- Item one
- Item two
- Nested item (indent with 2 spaces)
- Another nested item
- Item three
Ordered list:
1. First step
2. Second step
3. Third step
Links und Bilder
[Link text](https://example.com)
[Link with title](https://example.com "Hover tooltip")
Blockzitate
> This is a blockquote.
> It can span multiple lines.
> You can nest blockquotes:
> > Like this.
Horizontale Linie
---
(Drei oder mehr Bindestriche, Sternchen oder Unterstriche in einer eigenen Zeile)
Code-Blöcke
Inline-Code wird mit einfachen Backticks dargestellt:
Use the `console.log()` function for debugging.
Umrandete Code-Blöcke verwenden dreifache Backticks mit einer optionalen Sprachkennung für die Syntaxhervorhebung:
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
Unterstützte Sprachen sind unter anderem javascript, typescript, python, bash, sql, json, yaml, css, html, go, rust und viele weitere – je nach Renderer.
Tabellen
Markdown-Tabellen verwenden Pipe-Zeichen und Bindestriche:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Cell A | Cell B | Cell C |
| Cell D | Cell E | Cell F |
Spalten mit Doppelpunkten in der Trennzeile ausrichten:
| Left | Center | Right |
|:-----|:------:|------:|
| L | C | R |
Tabellen sind Teil von GitHub Flavored Markdown (GFM) und nicht im Standard-Markdown enthalten. Sie funktionieren in GitHub, VS Code, den meisten Dokumentationsplattformen und MDX.
Aufgabenlisten (GFM)
- [x] Write the introduction
- [x] Add code examples
- [ ] Review and publish
- [ ] Add images
Auf GitHub werden daraus interaktive Checkboxen. In modernen Markdown-Renderern weit verbreitet.
Markdown-Varianten
Das ursprüngliche Markdown ist bewusst minimal gehalten. Inzwischen gibt es zahlreiche Erweiterungen:
| Variante | Verwendet in | Wesentliche Ergänzungen |
|---|---|---|
| CommonMark | Viele Plattformen | Standardisierte Spezifikation |
| GitHub Flavored (GFM) | GitHub, GitLab | Tabellen, Aufgabenlisten, Durchstreichen, Autolinks |
| MDX | React-Seiten | JSX-Komponenten in Markdown |
| Pandoc Markdown | Wissenschaftliche Dokumente | Fußnoten, Zitate, Mathematik |
| MultiMarkdown | macOS-Tools | Tabellen, Metadaten, Fußnoten |
Im Zweifelsfall GFM verwenden – es ist die am weitesten verbreitete erweiterte Variante.
Front Matter
Viele Markdown-Prozessoren unterstützen YAML-Front-Matter am Anfang einer Datei für Metadaten:
---
title: "My Article Title"
date: "2026-03-24"
author: "Jane Doe"
tags: ["markdown", "writing", "tools"]
published: true
---
# Article content starts here
Front Matter wird getrennt vom Dokumentkörper verarbeitet und für Dinge wie Seitentitel, Datumsangaben und SEO-Metadaten verwendet.
MDX: Markdown + JSX
MDX ist Markdown, das React-Komponenten enthalten kann. Es eignet sich ideal für Dokumentationen und Blogbeiträge auf React-basierten Seiten (Next.js, Gatsby, Astro):
import { Alert } from '../components/Alert'
## Important note
<Alert type="warning">
This feature is deprecated in v3.
</Alert>
Regular **Markdown** content continues below.
Das verbindet die Einfachheit von Markdown mit der Leistungsfähigkeit interaktiver Komponenten.
Sonderzeichen maskieren
Stelle Markdown-Sonderzeichen einen Backslash voran, um sie wörtlich darzustellen:
\*not italic\*
\# not a heading
\[not a link\]
Tipps für bessere Markdown-Dokumente
- Ein Satz pro Zeile – Sorgt für sauberere Diffs in Git; die Darstellung bleibt identisch, da Markdown einzelne Zeilenumbrüche ignoriert.
- Leerzeile zwischen Blöcken – Lasse stets eine Leerzeile zwischen Absätzen, Überschriften, Listen und Code-Blöcken.
- Einheitliche Listenzeichen – Entscheide dich für
-oder*bei ungeordneten Listen und halte das im gesamten Projekt konsequent durch. - Referenz-Links für wiederkehrende URLs – Einmal definieren, mehrfach verwenden:
See the [documentation][docs] and [changelog][docs]. [docs]: https://example.com/docs - Alt-Text für jedes Bild – Unverzichtbar für Barrierefreiheit und SEO.
Lesbarkeit prüfen
Markdown erleichtert das Schreiben – aber leichtes Schreiben kann schwer lesbaren Text erzeugen. Nutze unser Tool Readability Score, um Flesch-Kincaid-Leseklasse, Satzkomplexität und Verwendung des Passivs zu überprüfen. Strebe für ein allgemeines Publikum eine klare, prägnante Sprache auf Leseklasse 8–10 an.
Markdown gehört zu den Werkzeugen, die man in 10 Minuten lernt und von denen man ein Leben lang profitiert. Fang noch heute damit an – deine zukünftigen Mitarbeiter (und dein zukünftiges Ich) werden es dir danken.