Markdown Vollständige Anleitung: Syntax, Tipps & Best Practices

· 12 Min. Lesezeit

Inhaltsverzeichnis

Was ist Markdown?

Markdown ist eine leichtgewichtige Auszeichnungssprache, die 2004 von John Gruber in Zusammenarbeit mit Aaron Swartz entwickelt wurde. Sie ermöglicht es Ihnen, formatierten Text mit einfacher Klartextsyntax zu schreiben, der auch ohne Rendering lesbar bleibt. Anstatt Schaltflächen in einem Textverarbeitungsprogramm anzuklicken oder ausführliche HTML-Tags zu schreiben, verwenden Sie einfache, intuitive Zeichen wie # für Überschriften, ** für fetten Text und - für Listen.

Die Philosophie hinter Markdown ist elegant einfach: Der Quelltext sollte genauso lesbar sein wie die gerenderte Ausgabe. Wenn Sie eine Markdown-Datei in einem beliebigen Texteditor öffnen, können Sie ihre Struktur und ihren Inhalt sofort verstehen, ohne spezielle Software oder Rendering-Engines zu benötigen.

Markdown ist zum De-facto-Standard für technisches Schreiben, Dokumentation, README-Dateien, Blogbeiträge und Notizen in der Softwareentwicklungswelt geworden. Große Plattformen wie GitHub, GitLab, Reddit, Stack Overflow, Discord, Slack, Notion und Obsidian unterstützen Markdown nativ, was es zu einer unverzichtbaren Fähigkeit für Entwickler, technische Redakteure und Content-Ersteller macht.

Warum Markdown verwenden?

Profi-Tipp: Wenn Sie regelmäßig mit Markdown-Dateien arbeiten, probieren Sie unseren Markdown-Editor für Live-Vorschau und Syntax-Hervorhebung aus, oder verwenden Sie den Markdown-zu-HTML-Konverter, um Ihre Dokumente sofort umzuwandeln.

Überschriften und Dokumentstruktur

Überschriften sind das Rückgrat der Dokumentstruktur in Markdown. Sie verwenden das #-Symbol, wobei die Anzahl der Rauten die Überschriftenebene von 1 bis 6 bestimmt:

# Überschrift 1
## Überschrift 2
### Überschrift 3
#### Überschrift 4
##### Überschrift 5
###### Überschrift 6

Fügen Sie immer ein Leerzeichen nach dem #-Symbol ein – die meisten Markdown-Prozessoren erfordern dies, und es verbessert die Lesbarkeit. Die gerenderte Ausgabe erstellt ordnungsgemäße HTML-Überschriften-Tags (<h1> bis <h6>), die für Dokumentstruktur, Barrierefreiheit und SEO entscheidend sind.

Best Practices für Überschriften

Verwenden Sie Überschriftenebenen sequenziell, ohne Ebenen zu überspringen. Springen Sie nicht von H1 zu H3 – dies bricht die Dokumenthierarchie und verursacht Barrierefreiheitsprobleme für Screenreader-Nutzer. Betrachten Sie Überschriften als Gliederung: Jede Ebene sollte logisch in die vorherige eingebettet sein.

Die meisten Dokumente sollten nur eine H1-Überschrift (den Titel) haben, mit H2-Überschriften für Hauptabschnitte und H3-H6 für Unterabschnitte. Dies schafft eine klare Informationshierarchie, die sowohl Menschen als auch Suchmaschinen verstehen können.

Schneller Tipp: Viele Markdown-Prozessoren generieren automatisch Anker-Links für Überschriften, sodass Sie direkt auf bestimmte Abschnitte verlinken können. GitHub konvertiert beispielsweise "## Erste Schritte" in einen Anker, auf den Sie mit #erste-schritte verweisen können.

Alternative Überschriftensyntax

Markdown unterstützt auch eine alternative Syntax für H1- und H2-Überschriften mit Unterstreichungen:

Überschrift 1
=============

Überschrift 2
-------------

Obwohl diese Syntax gültig ist, ist die Rauten-Syntax gebräuchlicher und unterstützt alle sechs Überschriftenebenen, was sie zur bevorzugten Wahl für die meisten Autoren macht.

Grundlagen der Textformatierung

Markdown bietet einfache, intuitive Syntax für gängige Textformatierungsanforderungen. Diese Formatierungsoptionen funktionieren inline innerhalb von Absätzen und können für komplexere Gestaltung kombiniert werden.

Format Syntax Alternative Ergebnis
Fett **fett** __fett__ fett
Kursiv *kursiv* _kursiv_ kursiv
Fett + Kursiv ***beides*** ___beides___ beides
Durchgestrichen ~~gelöscht~~ — gelöscht
Inline-Code `code` — code
Tiefgestellt H~2~O — H2O
Hochgestellt X^2^ — X2
Hervorhebung ==markiert== — markiert

Details zur Hervorhebungssyntax

Sowohl Sternchen (*) als auch Unterstriche (_) funktionieren für Hervorhebungen, aber Sternchen werden häufiger verwendet und empfohlen. Der Hauptunterschied: Sternchen funktionieren mitten im Wort (un*verdammt*glaublich), während Unterstriche Wortgrenzen erfordern.

Für fetten Text verwenden Sie doppelte Sternchen oder Unterstriche. Für kursiven Text verwenden Sie einfache Sternchen oder Unterstriche. Kombinieren Sie drei für fett-kursiven Text. Diese Konsistenz macht Ihren Markdown-Quelltext lesbarer und vorhersehbarer.

Profi-Tipp: Verwenden Sie beim Schreiben technischer Dokumentation `Backticks` für Inline-Code, Funktionsnamen, Dateipfade und Befehlszeilenargumente. Diese visuelle Unterscheidung hilft Lesern, Code-Elemente innerhalb des Fließtexts schnell zu identifizieren.

Sonderzeichen maskieren

Wenn Sie wörtliche Sternchen, Unterstriche oder andere Markdown-Syntaxzeichen anzeigen müssen, maskieren Sie sie mit einem Backslash:

Dies ist \*nicht kursiv\* und \*\*nicht fett\*\*
Verwenden Sie \#, um eine Raute ohne Überschrift anzuzeigen

Häufige Zeichen, die maskiert werden müssen, sind: \ ` * _ { } [ ] ( ) # + - . !

Listen: Geordnet, ungeordnet und verschachtelt

Listen sind grundlegend für die Organisation von Informationen in Markdown. Sie sind einfach zu erstellen und unterstützen Verschachtelung für hierarchische Inhalte.

Ungeordnete Listen

Erstellen Sie ungeordnete (Aufzählungs-)Listen mit -, * oder + gefolgt von einem Leerzeichen. Alle drei Markierungen funktionieren identisch, aber Konsistenz innerhalb eines Dokuments verbessert die Lesbarkeit:

- Erstes Element
- Zweites Element
- Drittes Element
  - Verschachteltes Element (mit 2 Leerzeichen einrücken)
  - Weiteres verschachteltes Element
- Viertes Element

Die Standardeinrückung für verschachtelte Listen beträgt zwei Leerzeichen, obwohl einige Parser vier akzeptieren. Bleiben Sie bei zwei Leerzeichen für maximale Kompatibilität.

Geordnete Listen

Geordnete (nummerierte) Listen verwenden Zahlen gefolgt von Punkten und einem Leerzeichen:

1. Erster Schritt
2. Zweiter Schritt
3. Dritter Schritt
   1. Unterschritt A
   2. Unterschritt B
4. Vierter Schritt

Hier ist eine nützliche Funktion: Die tatsächlichen Zahlen, die Sie verwenden, spielen keine Rolle. Markdown nummeriert Listen beim Rendern automatisch sequenziell. Sie können 1. für jedes Element verwenden, was das Neuordnen von Elementen ohne Neunummerierung erleichtert:

1. Erstes Element
1. Zweites Element
1. Drittes Element

Dies wird als ordnungsgemäß nummerierte 1, 2, 3 Liste gerendert. Diese Technik ist besonders hilfreich bei der Pflege langer Listen oder häufigem Neuordnen von Elementen.

Aufgabenlisten

Viele Markdown-Varianten (einschließlich GitHub Flavored Markdown) unterstützen Aufgabenlisten mit Kontrollkästchen:

- [x] Erledigte Aufgabe
- [ ] Unerledigte Aufgabe
- [ ] Weitere unerledigte Aufgabe

Aufgabenlisten sind unschätzbar für Projektmanagement, Issue-Tracking und To-Do-Listen in der Dokumentation.

Schneller Tipp: Um mehrere Absätze oder Codeblöcke innerhalb eines Listenelements einzufügen, rücken Sie den nachfolgenden Inhalt so ein, dass er mit dem ersten Zeichen des Listenelementtexts übereinstimmt (typischerweise 3-4 Leerzeichen für ungeordnete Listen, 4 Leerzeichen für geordnete Listen).

Definitionslisten

Einige erweiterte Markdown-Syntaxen unterstützen Definitionslisten für Glossare und Begriffsdefinitionen:

Begriff 1
: Definition für Begriff 1

Begriff 2
: Erste Definition für Begriff 2
: Zweite Definition für Begriff 2

Obwohl nicht universell unterstützt, sind Definitionslisten nützlich für technische Dokumentation und Glossare.

Markdown macht es einfach, Hyperlinks und Bilder hinzuzufügen, während der Quelltext lesbar bleibt.

Inline-Links

Die gebräuchlichste Link-Syntax verwendet eckige Klammern für den Linktext und runde Klammern für die URL:

[Linktext](https://example.com)
[Link mit Titel](https://example.com "Hover-Text")

Der optionale Titeltext erscheint als Tooltip, wenn Benutzer über den Link fahren. Dies ist nützlich, um zusätzlichen Kontext bereitzustellen, ohne den sichtbaren Linktext zu überladen.

Referenz-Links

Für Dokumente mit vielen Links oder wiederholten URLs verbessern Referenz-Links die Lesbarkeit:

Dies ist [ein Link][1] und hier ist [ein weiterer Link][2].

[1]: https://example.com
[2]: https://example.com/seite "Optionaler Titel"

Sie können auch beschreibende Referenzen anstelle von Zahlen verwenden:

Schauen Sie sich [Google][google] und [GitHub][gh] an.

[google]: https://google.com
[gh]: https://github.com

Referenzdefinitionen können überall im Dokument erscheinen und werden in der Ausgabe nicht gerendert. Viele Autoren platzieren sie am Ende von Abschnitten oder am Dokumentende.

Automatische Links

Umschließen Sie URLs oder E-Mail-Adressen mit spitzen Klammern, um automatische Links zu erstellen:

<https://example.com>
<[email protected]>

Die meisten modernen Markdown-Parser konvertieren auch nackte URLs automatisch in anklickbare Links, obwohl dieses Verhalten nicht auf allen Plattformen garantiert ist.

Bilder

Die Bildsyntax ist nahezu identisch mit der Link-Syntax, mit einem Ausrufezeichen als Präfix:

![Alt-Text](bild.jpg)
![Alt-Text](bild.jpg "Bildtitel")

Der Alt-Text ist entscheidend für die Barrierefreiheit – er beschreibt das Bild für Screenreader-Nutzer und wird angezeigt, wenn das Bild nicht geladen werden kann. Geben Sie immer aussagekräftigen Alt-Text an, der den Inhalt und Zweck des Bildes vermittelt.

Referenz-Syntax funktioniert auch für Bilder:

![Logo][logo]

[logo]: /images/logo.png "Firmenlogo"

Profi-Tipp: Standard-Markdown unterstützt keine Bildgrößenanpassung oder -ausrichtung. Für diese Funktionen müssen Sie HTML direkt verwenden: <img src="bild.jpg" width="300" alt="Beschreibung"> oder sich auf erweiterte Markdown-Syntax verlassen, die spezifisch für Ihre Plattform ist.

Bilder verlinken

Um ein Bild anklickbar zu machen, umschließen Sie die Bildsyntax mit Link-Syntax:

[![Alt-Text](vorschau.jpg)](vollbild.jpg)

Diese Technik wird häufig für Bildergalerien oder zum Verlinken von Vorschaubildern zu Vollauflösungsversionen verwendet.

Codeblöcke und Syntax-Hervorhebung

Markdown zeichnet sich durch die Darstellung von Code aus, was es zum bevorzugten Format für technische Dokumentation und Programmier-Tutorials macht.

Inline-Code

Für kurze Code-Schnipsel innerhalb von Text verwenden Sie einfache Backticks:

Verwenden Sie die `print()`-Funktion zur Ausgabe.
Die `config.json`-Datei enthält Einstellungen.

Wenn Ihr Code Backticks enthält, verwenden Sie doppelte Backticks zum Umschließen:

``Verwenden Sie `Backticks` im Code``

Umzäunte Codeblöcke

Für mehrzeilige Codeblöcke verwenden Sie dreifache Backticks (```) oder dreifache Tilden (~~~) vor und nach dem Code:

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

Dies erstellt einen ordnungsgemäß formatierten Codeblock mit Monospace-Schrift und erhaltenen Leerzeichen.

Syntax-Hervorhebung

Geben Sie die Programmiersprache unmittelbar nach den öffnenden Backticks an, um Syntax-Hervorhebung zu aktivieren:

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

```python
def greet(name):
    return f"Hallo, {name}!"
```

```bash
#!/bin/bash