Markdown wurde von John Gruber im Jahr 2004 mit einem einzigen, eleganten Ziel entwickelt: einfachen Text schreiben, der sich natürlich liest, und ihn dann in sauberes HTML umwandeln. Zwei Jahrzehnte später ist es überall — GitHub-README-Dateien, Pull-Request-Beschreibungen, Slack-Nachrichten, Notion-Dokumente, Blog-Beiträge, KI-Chat-Antworten. Es ist eines jener Werkzeuge, die man jeden Tag für den Rest der Karriere verwenden wird, ob man bewusst darüber nachdenkt oder nicht.
Was Markdown wirklich ist
Markdown ist einfacher Text mit leichtgewichtiger, lesbarer Syntax darüber gelegt. Ein # am Anfang einer Zeile wird zu einem <h1>. Ein Wort in **doppelte Sternchen** einwickeln macht es fett. Backticks erzeugen Inline-Code. Die zentrale Designphilosophie ist, dass Markdown-Quelltext so wie er ist lesbar sein soll — sogar bevor er gerendert wird. Wenn man schon einmal eine E-Mail mit *Sternchen um Betonung* geschrieben oder Bindestriche für eine Aufzählungsliste verwendet hat, schrieb man bereits etwas, das Markdown sehr nahe kommt.
Hier ist ein schnelles Vorher-Nachher. Das Markdown links erzeugt das HTML rechts:
## Getting Started
Install the package with **npm**:
`npm install my-library`
Then import it in your project — see the [docs](https://example.com) for details.<h2>Getting Started</h2>
<p>Install the package with <strong>npm</strong>:</p>
<p><code>npm install my-library</code></p>
<p>Then import it in your project — see the <a href="https://example.com">docs</a> for details.</p>Man schreibt die obere Hälfte; ein Markdown-Prozessor erzeugt die untere. Dieser Übersetzungsschritt ist unsichtbar, sobald er im Editor oder in der CI-Pipeline ist.
Kernsyntax — Der Teil, den jede Variante teilt
Welche Markdown-Variante man auch verwendet, diese Bausteine funktionieren überall:
- Überschriften —
# H1,## H2,### H3(bis zu sechs Ebenen) - Fett und kursiv —
**fett**,*kursiv*,***beides*** - Links —
[Linktext](https://url.com) - Bilder —
 - Inline-Code —
`Backtick`umschließt einen Snippet; drei Backticks öffnen einen umzäunten Codeblock - Blockzitate — eine Zeile mit
>beginnen - Ungeordnete Listen — Zeilen, die mit
-oder*beginnen - Geordnete Listen — Zeilen, die mit
1.,2.usw. beginnen - Horizontale Linie — drei oder mehr Bindestriche:
---
Hier ist ein realistischer README-Snippet, der all das oben Genannte zusammen verwendet:
# json-transform
> A zero-dependency library for transforming JSON structures.
## Installation
```bash
npm install json-transform
```
## Usage
```js
import { transform } from 'json-transform';
const result = transform(input, schema);
```
## Features
- **Fast** — processes 10k objects/sec on average hardware
- *Typed* — ships with full TypeScript definitions
- Zero runtime dependencies
See the [full documentation](https://json-transform.dev/docs) for advanced options.
---
MIT LicenseDas Varianten-Problem — CommonMark, GFM und andere
Hier ist der Haken: „Markdown" ist keine einheitliche Sache. Grubers ursprüngliche Spezifikation von 2004 war absichtlich locker, was zu Jahren inkompatibler Implementierungen führte. Verschiedene Parser behandelten Grenzfälle — verschachtelte Listen, Leerzeilen in Blockzitaten, Rangfolge zwischen Betonung und Links — auf unterschiedliche Weisen. Dieselbe Quelldatei würde in verschiedenen Tools unterschiedlich gerendert.
CommonMark (2014 gestartet) hat das behoben. Eine Gruppe von Entwicklern — darunter Personen von GitHub, Stack Overflow und Reddit — schrieb eine strenge, eindeutige Spezifikation, die jeden Grenzfall mit einer Testsuite von 652 Beispielen abdeckt. Die meisten modernen Tools verwenden jetzt CommonMark als Basis.
GitHub erweiterte CommonMark dann mit eigenen Ergänzungen und veröffentlichte GitHub Flavored Markdown (GFM). GFM ist das, was man in GitHub-READMEs, Issues und Pull Requests schreibt. Viele andere Tools haben auch GFM-Erweiterungen übernommen, aber nicht alle — daher wird das, was auf GitHub gerendert wird, möglicherweise nicht gleich in einem statischen Site-Generator oder einer Notiz-App gerendert. Zu wissen, welche Variante das eigene Tool unterstützt, spart viel Kopfzerbrechen.
GitHub Flavored Markdown Erweiterungen
GFM fügt fünf Funktionen über CommonMark hinzu, die man auf GitHub und in jedem Tool, das das GFM-Superset unterstützt, ständig verwenden wird:
Tabellen — pipe-begrenzte Spalten mit einer Trennzeile aus Bindestrichen:
| Method | Returns | Mutates? |
|---------|---------------|----------|
| map() | new array | No |
| filter()| new array | No |
| sort() | same array | Yes |Aufgabenlisten — Kontrollkästchen in Issues und Pull Requests:
- [x] Write unit tests
- [x] Update CHANGELOG
- [ ] Add migration guide
- [ ] Tag releaseDurchgestrichen — Text in doppelte Tilden einwickeln:
~~deprecated API~~ — use `newMethod()` insteadUmzäunte Codeblöcke mit Sprachhinweisen — der Sprachbezeichner nach den öffnenden Backticks löst Syntaxhervorhebung aus:
```python
def parse_config(path: str) -> dict:
with open(path) as f:
return json.load(f)
```Autolinks — bloße URLs wie https://example.com werden automatisch anklickbar gemacht, ohne [Text](URL)-Syntax zu benötigen. Das ist praktisch in Issue-Kommentaren, kann aber überraschend sein, wenn man eine URL einfügt, die man nicht verlinken möchte.
Wo man Markdown in der Praxis verwenden wird
Markdown taucht an mehr Stellen auf, als die meisten Entwickler erwarten, wenn sie es zum ersten Mal kennenlernen:
- GitHub und GitLab — README-Dateien, Issues, Pull-Request-Beschreibungen, Wikis und sogar Commit-Nachrichteninhalte. Jedes Repository, das man anfasst, wird mindestens eine README.md haben.
- Statische Site-Generatoren — Jekyll, Hugo, Eleventy, Astro und Next.js akzeptieren alle Markdown-Inhaltsdateien. Man schreibt Beiträge in
.md-Dateien, und der Generator wandelt sie zur Build-Zeit in HTML-Seiten um. - Dokumentations-Tools — MkDocs, Docusaurus und GitBook sind vollständig rund um Markdown-Quellen aufgebaut. Open-Source-Bibliotheken verwenden nahezu universell eines davon.
- Notiz-Apps — Obsidian, Notion, Bear und Typora verwenden alle Markdown als natives Format (mit unterschiedlichen Erweiterungen). Notizen sind portable Klartextdateien, keine proprietäre Datenbank.
- CMS-Plattformen — Ghost verwendet Markdown nativ. Contentful und Strapi unterstützen beide Markdown-Felder. Headless-CMS-Setups speichern Long-Form-Inhalte typischerweise als Markdown-Strings.
- KI-Tools — ChatGPT und Claude geben standardmäßig Markdown aus. Code-Snippets, fette Begriffe und Aufzählungslisten in KI-Antworten sind Markdown — die Chat-UI rendert sie, aber der zugrunde liegende Text ist
**fett**und```python.
Markdown vs HTML — Wann welches verwenden
Markdown wird in HTML umgewandelt, kann aber nicht alles ausdrücken, was HTML kann. Es gibt kein Äquivalent für <div class="card">, data-*-Attribute oder aria-*-Attribute. Für einfachen Prosainhalt — Dokumentation, READMEs, Blog-Beiträge, Changelogs — ist Markdown schneller zu schreiben und in seiner Rohform weit lesbarer. Für komplexe UI-Komponenten, benutzerdefinierte Layouts oder Barrierefreiheitsanmerkungen, die spezifische Attribute erfordern, braucht man HTML.
Die gute Nachricht: Die meisten Markdown-Prozessoren erlauben rohes HTML inline. Man kann beides mischen. Wenn man ein <figure> mit einem <figcaption> oder ein <details>-Offenlegungs-Widget braucht, einfach das HTML direkt in die .md-Datei schreiben. Der Prozessor gibt es unverändert weiter. Diesen Ausweg sparsam verwenden — wenn mehr als ein Drittel der Datei rohes HTML ist, könnte man genauso gut HTML direkt schreiben und unseren HTML Formatter verwenden, um es sauber zu halten.
- Markdown verwenden für: Dokumentation, READMEs, Changelogs, Blog-Beiträge, Wissensdatenbankartikeln, API-Beschreibungsfelder
- HTML verwenden für: präzises Layout, benutzerdefinierte Komponenten, Formulare, Elemente, die spezifische Attribute erfordern
- Beide mischen, wenn: hauptsächlich Prosainhalt mit einer Handvoll struktureller Ausnahmen (eine responsive Tabelle, ein Video-Embed)
Zusammenfassung
Markdown ist täuschend einfach — es sieht nach nur einer Handvoll Satzzeichen-Regeln aus, aber es treibt die Dokumentation für praktisch jedes große Open-Source-Projekt an. Die Kernsyntax zu erlernen dauert etwa zehn Minuten. Die Unterschiede zwischen Varianten zu verstehen (CommonMark vs GFM vs was auch immer der eigene SSG verwendet) ist das, was Entwickler trennt, die gelegentlich mit ihren Dokumentations-Tools kämpfen, von denen, die das nicht tun.
Die autoritativen Referenzen: CommonMark für die standardisierte Spezifikation, GitHub Flavored Markdown für die GitHub-Erweiterungen und der Markdown Guide für eine praktische Kurzreferenz. Für den täglichen Schreibbedarf ermöglicht unsere Markdown-Vorschau das sofortige Sehen der gerenderten Ausgabe, und der Markdown Formatter hält die Quelldateien konsistent.