Markdown-Syntax: Spickzettel mit Beispielen
Finde die passende Schreibweise, kopiere ein Beispiel und prüfe das Ergebnis in der Vorschau. Der Spickzettel trennt portable CommonMark-Grundlagen von verbreiteten Erweiterungen wie Tabellen, Aufgabenlisten und Durchstreichung in GitHub Flavored Markdown.
Markdown kurz erklärt
Markdown verwendet einfache Zeichen, um Struktur zu beschreiben. Rautezeichen stehen für Überschriften, Sternchen für Hervorhebung, Bindestriche für Listen und eckige mit runden Klammern für Links. Tabellen, Aufgabenlisten und Durchstreichung sind verbreitete GFM-Erweiterungen und nicht in jedem Renderer verfügbar.
So nutzt du den Markdown-Spickzettel
Kopiere nicht blind: prüfe, welchen Markdown-Dialekt deine Zielplattform verwendet.
- 1Element findenWähle Überschriften, Textformatierung, Listen, Links, Bilder, Code, Zitate, Tabellen oder Zeilenumbrüche.
- 2Beispiel anpassenKopiere die Schreibweise und ersetze Platzhalter, Linkziele, Alternativtext oder Spaltenwerte.
- 3Im Zielrenderer prüfenNutze die Vorschau und teste zusätzlich GitHub, das CMS oder die Anwendung, in der der Text erscheinen soll.
Überschriften
Ein bis sechs Rautezeichen am Zeilenanfang bestimmen die Ebene. Nach den Zeichen steht ein Leerzeichen. Verwende Ebenen für die Gliederung, nicht bloß für eine kleinere Schrift.
# Dokumenttitel
## Hauptabschnitt
### UnterabschnittErgebnis: Ein Dokumenttitel, darunter ein Hauptabschnitt und ein untergeordneter Abschnitt.
- In einem eigenständigen Dokument genügt meist ein H1.
- Überspringe Ebenen nicht ohne strukturellen Grund.
- Leere Zeilen rund um Abschnitte verbessern die Lesbarkeit der Quelle.
Absätze und Zeilenumbrüche
Eine Leerzeile trennt Absätze. Ein harter Umbruch innerhalb desselben Absatzes kann mit zwei Leerzeichen am Zeilenende erzeugt werden. Backslash und `<br>` sind stärker vom Dialekt abhängig.
Erster Absatz.
Zweiter Absatz.
Erste Zeile mit zwei Leerzeichen.
Zweite Zeile.Ergebnis: Zwei Absätze; im zweiten Beispiel ein bewusster Zeilenwechsel innerhalb des Absatzes.
- Ein einzelner Quellzeilenwechsel kann im Ergebnis verschwinden.
- Nachgestellte Leerzeichen sind unsichtbar und werden von Formatierern manchmal entfernt.
- Für normale Fließtexte den automatischen Umbruch des Zielsystems verwenden.
Fett, kursiv und kombiniert
Ein Sternchenpaar hebt Text kursiv hervor, zwei Sternchenpaare fett und drei Paare fett sowie kursiv. Unterstriche funktionieren ebenfalls, können aber innerhalb von Wörtern leichter missverstanden werden.
*kursiv*
**fett**
***fett und kursiv***Ergebnis: Drei Hervorhebungsstufen ohne Änderung des Wortlauts.
- Sternchen direkt an den Text setzen.
- Hervorhebung sparsam verwenden.
- Für gelöschten Text ist Durchstreichung eine GFM-Erweiterung.
Aufzählungen
Ein Bindestrich, Sternchen oder Pluszeichen mit folgendem Leerzeichen beginnt einen Listenpunkt. Einrückung erzeugt eine Unterliste.
- Planung
- Umsetzung
- Tests
- DokumentationErgebnis: Zwei Hauptpunkte, wobei Tests und Dokumentation unter Umsetzung eingerückt sind.
- Verwende im selben Dokument einen konsistenten Marker.
- Unterlisten mit genügend Leerzeichen einrücken.
- Eine Leerzeile vor einer Liste verhindert, dass sie an den vorherigen Absatz geklebt wird.
Nummerierte Listen
Eine Zahl mit Punkt und Leerzeichen beginnt eine geordnete Liste. Viele Renderer nummerieren automatisch; sichtbare Quellzahlen sollten trotzdem die beabsichtigte Reihenfolge verständlich machen.
1. Datei öffnen
2. Inhalt prüfen
3. Ergebnis speichernErgebnis: Drei Schritte in einer nummerierten Reihenfolge.
- Für verschachtelte Schritte ausreichend einrücken.
- Bei längeren Punkten Folgezeilen lesbar ausrichten.
- Nicht jede Zahl mit Punkt ist automatisch ein sinnvoller Prozessschritt.
Aufgabenlisten
Ein Listenmarker mit `[ ]` erzeugt eine offene und `[x]` eine erledigte Aufgabe. Die Darstellung ist eine verbreitete GFM-Erweiterung.
- [ ] Ausgabe prüfen
- [x] Quelle speichernErgebnis: Eine offene und eine als erledigt markierte Aufgabe.
- Zwischen Klammer und Aufgabentext steht ein Leerzeichen.
- Interaktive Anklickbarkeit hängt von der Plattform ab.
- In CommonMark ohne Erweiterung kann die Klammer als Text erscheinen.
Links
Der sichtbare Linktext steht in eckigen Klammern, das Ziel direkt danach in runden Klammern. Beschreibender Text ist hilfreicher als „hier klicken“.
[Markdown-Spickzettel](/markdown-cheat-sheet)
[CommonMark](https://commonmark.org/)Ergebnis: Ein interner und ein externer Link mit verständlichem Linktext.
- Relative Ziele nach einer Migration prüfen.
- Klammern und Leerzeichen in URLs gegebenenfalls korrekt kodieren.
- Wichtige Links nach der Veröffentlichung anklicken und testen.
Bilder und Alternativtext
Die Bildsyntax entspricht einem Link mit vorangestelltem Ausrufezeichen. Der Text in eckigen Klammern beschreibt die Funktion des Bildes, wenn es nicht gesehen werden kann.
Ergebnis: Ein Bildverweis mit beschreibendem Alternativtext.
- Der .md-Text bettet die Bilddaten normalerweise nicht ein.
- Relative Pfade funktionieren nur, wenn Datei und Ordner gemeinsam verschoben werden.
- Standard-Markdown besitzt keine portable Einstellung für Bildbreite; dafür wäre zielabhängiges HTML nötig.
Inline-Code
Ein einzelnes Backtick-Paar kennzeichnet einen Befehl, Dateinamen oder kurzen Code innerhalb eines Satzes.
Führe `npm run build` aus und öffne danach `dist/index.html`.Ergebnis: Befehl und Dateipfad erscheinen in einer nicht proportionalen Code-Darstellung.
- Inline-Code nicht zusätzlich fett markieren.
- Für einen Backtick im Inhalt können längere Backtick-Begrenzer nötig sein.
- Befehle nur übernehmen, wenn ihre Wirkung verstanden ist.
Codeblöcke
Drei Backticks auf eigenen Zeilen umschließen einen Codeblock. Eine Sprachangabe nach dem öffnenden Fence kann Syntaxhervorhebung aktivieren, wenn der Renderer sie unterstützt.
```javascript
const bereit = true;
console.log(bereit);
```Ergebnis: Ein JavaScript-Codeblock mit erhaltener Einrückung.
- Öffnenden und schließenden Fence jeweils auf eine eigene Zeile setzen.
- Die Sprachangabe beeinflusst Darstellung, führt den Code aber nicht aus.
- Bei Backticks im Code einen längeren Fence oder Tilden verwenden.
Zitate und Hinweise
Ein Größer-als-Zeichen mit folgendem Leerzeichen beginnt ein Blockzitat. Jede Absatzzeile eines längeren Zitats sollte eindeutig markiert sein.
> Gute Werkzeuge erklären auch ihre Grenzen.
>
> Prüfe immer die heruntergeladene Datei.Ergebnis: Ein zweizeiliges Blockzitat mit eigenem Absatz.
- Eine Quellenangabe als normalen Absatz oder Link ergänzen.
- Verschachtelte Zitate sind möglich, werden aber schnell unübersichtlich.
- Ein Blockzitat ist keine universelle farbige Hinweisbox.
Horizontale Trennlinie
Mindestens drei Bindestriche, Sternchen oder Unterstriche auf einer eigenen Zeile erzeugen eine thematische Trennung.
Abschnitt davor.
---
Abschnitt danach.Ergebnis: Eine horizontale Trennlinie zwischen zwei Abschnitten.
- Leerzeilen rund um die Linie vermeiden Verwechslungen mit Setext-Überschriften.
- Im Folienkonverter trennt `---` zusätzlich Folien; dort gilt der Werkzeugkontext.
- Eine Trennlinie ersetzt keine logische Überschriftenstruktur.
Sonderzeichen maskieren
Ein Backslash vor einem Markdown-Zeichen zeigt es als wörtliches Zeichen statt als Formatierung.
\*kein kursiver Text\*
\# keine ÜberschriftErgebnis: Sternchen und Rautezeichen bleiben sichtbar.
- Nur Zeichen maskieren, die der Renderer sonst als Syntax deutet.
- In Codebereichen ist eine zusätzliche Maskierung meist nicht erforderlich.
- Bei Tabellen muss ein senkrechter Strich in einer Zelle als `\|` maskiert werden.
Tabellen
Eine Pipe-Tabelle benötigt eine Kopfzeile, eine Trennzeile mit mindestens drei Bindestrichen je Spalte und Datenzeilen. Doppelpunkte in der Trennzeile geben die Ausrichtung an.
| Format | Bearbeitbar |
| :--- | ---: |
| DOCX | Ja |
| PDF | Nein |Ergebnis: Eine links- und eine rechtsbündige Spalte mit zwei Datenzeilen.
- Pipe-Tabellen sind nicht Teil der CommonMark-Kernsyntax.
- Keine verbundenen oder portabel mehrzeiligen Zellen.
- Breite Tabellen auf Mobilgeräten und im Zielrenderer prüfen.
Kommentare und eingebettetes HTML
HTML-Kommentare können im Quelltext Hinweise verbergen, sofern der Zielrenderer HTML zulässt und nicht bereinigt. Eingebettetes HTML bindet ein Dokument stärker an die Zielplattform.
<!-- Interner Hinweis: Zahlen vor Veröffentlichung prüfen. -->
Sichtbarer Absatz.Ergebnis: Der Kommentar ist in vielen gerenderten Ansichten unsichtbar; der Absatz bleibt sichtbar.
- Es gibt keine universelle reine Markdown-Kommentarsyntax.
- Sensible Informationen gehören nicht in Kommentare, weil sie im Quelltext sichtbar bleiben.
- Sicherheitsfilter können HTML entfernen oder als Text darstellen.
Verbreitete GFM-Erweiterungen
GitHub Flavored Markdown ergänzt unter anderem Tabellen, Aufgabenlisten, Durchstreichung und automatische Linkerkennung. Andere Plattformen übernehmen davon nur einen Teil.
- [x] ~~Alter Entwurf~~
- [ ] Neue Fassung prüfenErgebnis: Eine erledigte, durchgestrichene Aufgabe und eine offene Aufgabe.
- GFM bedeutet nicht automatisch Discord-, Obsidian- oder Notion-Kompatibilität.
- Plattformspezifische Autolinks und Sicherheitsfilter gesondert prüfen.
- Für portable Dokumente zuerst die CommonMark-Grundelemente nutzen.
Kleine Markdown-Startdatei
Ein kurzes Dokument kombiniert Titel, Beschreibung, Abschnitt, Liste, Link und Code, ohne unnötige Erweiterungen zu benötigen.
# Projektname
Kurze **Beschreibung** des Projekts.
## Installation
1. `npm install` ausführen
2. [Dokumentation](https://example.com) lesenErgebnis: Eine klar gegliederte README-Grundlage.
- Datei als UTF-8 mit der Endung `.md` speichern.
- Nur einen H1 als Dokumenttitel verwenden.
- Links und Befehle vor der Veröffentlichung testen.
Wenn Markdown nicht wie erwartet aussieht
Die häufigsten Ursachen sind fehlende Leerzeichen, fehlende Leerzeilen, unvollständige Fences, unmaskierte Pipe-Zeichen und eine Erweiterung, die der Zielrenderer nicht unterstützt.
## Überschrift
- Listenpunkt
```text
Codeblock
```Ergebnis: Ein minimaler Test mit Überschrift, Liste und geschlossenem Codeblock.
- Problem auf ein kleinstes Beispiel reduzieren.
- Quelle und gerenderte Ansicht nebeneinander vergleichen.
- Dialekt und Zielplattform benennen, bevor du nach einer Syntaxlösung suchst.
CommonMark und GitHub Flavored Markdown
Die Grundsyntax ist weit verbreitet, Erweiterungen sind jedoch nicht universell. Prüfe den Editor, das CMS oder das Repository, in dem du veröffentlichst.
Überschriften, Absätze, Hervorhebung, Zitate, Listen, Code, Links, Bilder und horizontale Linien bilden die portable Basis.
GitHub Flavored Markdown ergänzt Tabellen, Aufgabenlisten, Durchstreichung und erweiterte Autolinks. Andere Renderer unterstützen davon möglicherweise nur einen Teil.
Die genauen Regeln stehen in den Spezifikationen: CommonMark · GFM
Häufige Fragen zur Markdown-Syntax
Welche Markdown-Syntax sollte ich zuerst lernen?
Beginne mit Überschriften, Absätzen, Hervorhebung, Listen, Links und Code. Tabellen und GFM-Erweiterungen kannst du später ergänzen.
Warum sieht Markdown auf verschiedenen Plattformen anders aus?
Renderer verwenden unterschiedliche Stile und Erweiterungen. Die Kernsyntax bleibt ähnlich, aber Tabellen, Aufgabenlisten, HTML und Zeilenumbrüche können abweichen.
Kann ich den gesamten Spickzettel speichern?
Ja. Die Seite kann eine .md-Startdatei mit Beispielen bereitstellen. Prüfe die Datei anschließend in deinem Zielrenderer.