Warum mit Markdown schreiben
Markdown ist eine leichtgewichtige Auszeichnungssprache, die einfache Symbole zur Formatierung verwendet. Autoren müssen die Maus nicht benutzen, konzentrieren sich auf den Inhalt, und die Formatierung wird automatisch generiert.
Vorteile:
- Klartext, mit jedem Editor öffnbar
- Versionskontrolle-freundlich (Git kann diff erstellen)
- In HTML, PDF, Word und andere Formate konvertierbar
- Geringe Lernkurve, Einstieg in 10 Minuten
Grundsyntax
Überschriften
# Überschrift Ebene 1
## Überschrift Ebene 2
### Überschrift Ebene 3
#### Überschrift Ebene 4
Es wird empfohlen, nur eine Überschrift der Ebene 1 pro Artikel zu verwenden.
Absätze
Trennen Sie Absätze durch Leerzeilen. Ohne Leerzeile gehört der Inhalt zum selben Absatz.
Hervorhebungen
**Fett**
*Kursiv*
~~Durchgestrichen~~
Listen
Unsortiert:
- Element
- Element
- Unterelement (eingerückt)
Sortiert:
1. Erstes Element
2. Zweites Element
Links und Bilder
[Linktext](https://example.com)
Code
Inline: code
Codeblock:
```javascript
const x = 1;
### Zitat
Zitatinhalt Zweite Zeile
### Trennlinie
## Erweiterte Syntax
### Tabellen
| Name | Alter |
|---|---|
| Tom | 25 |
### Aufgabenliste
- Erledigt
- Nicht erledigt
### Fußnoten
Textkörper^1
### Durchgestrichen
durchgestrichen
### Automatische Links
URLs werden automatisch in Links umgewandelt.
## Schreibtechniken
### Klare Überschriftenhierarchie
- Überschrift Ebene 1: Artikeltitel
- Überschrift Ebene 2: Hauptabschnitte
- Überschrift Ebene 3: Unterabschnitte
- Keine Ebenen überspringen (nicht von Ebene 1 direkt zu Ebene 3)
### Prägnante Absätze
- Ein Absatz, ein Gedanke
- Absätze nicht zu lang (3-5 Zeilen ideal)
- Lange Absätze durch Listen ersetzen
### Listen gut nutzen
Bei parallelem Inhalt sind Listen klarer als Absätze:
- Schritte mit sortierten Listen
- Parallele Elemente mit unsortierten Listen
- Vergleiche mit Tabellen
### Code-Sprache angeben
Geben Sie die Sprache von Codeblöcken an, um Syntaxhervorhebung zu aktivieren:
Bildbeschreibungen hinzufügen
Die Beschreibung in  ist wichtig:
- Wird angezeigt, wenn das Bild nicht lädt
- Wird von Bildschirmlesern für sehbehinderte Benutzer vorgelesen
- Gut für SEO
Klare Links
- Der Linktext beschreibt das Ziel, verwenden Sie nicht „klick hier“
- Externe Links mit vollständiger URL
- Interne Links mit relativem Pfad
Dokumentationsorganisation
Inhaltsverzeichnis am Anfang
Bei langen Dokumenten ein Inhaltsverzeichnis am Anfang platzieren, mit Links zu den Abschnitten. Erleichtert die Navigation.
Abschnitte mit Überschriften trennen
Trennen Sie Abschnitte mit Überschriften, nicht mit Trennlinien. Überschriften haben eine Hierarchie, Trennlinien nicht.
Code und Text trennen
Vor und nach Codeblöcken eine Leerzeile lassen, um sie vom Text abzuheben. Bessere Lesbarkeit.
Bilder an der richtigen Stelle platzieren
Bilder direkt nach dem zugehörigen Text platzieren, nicht am Ende sammeln. Leser, die der Reihenfolge folgen, sehen die Bilder rechtzeitig.
Editorauswahl
VS Code
- Kostenlos, leistungsstark
- Markdown-Erweiterung installieren (z. B. Markdown All in One)
- Echtzeit-Vorschau
- Geeignet für Entwickler
Typora
- WYSIWYG (What You See Is What You Get)
- Kein Vorschaufenster, direkte Bearbeitung des gerenderten Ergebnisses
- Kostenpflichtig, aber günstig
- Geeignet für konzentriertes Schreiben
Obsidian
- Lokale Wissensbasis
- Bidirektionale Links
- Reich an Erweiterungen
- Geeignet für Notizen und Wissensverwaltung
Online-Editoren
- StackEdit: Online-Markdown-Editor
- JianShu: Chinesische Schreibplattform
- Geeignet für gelegentliches Schreiben
Markdown in HTML konvertieren
Nach dem Schreiben von Markdown für die Webanzeige in HTML konvertieren. Mit dem Markdown-zu-HTML-Tool mit einem Klick konvertieren.
Häufige Fehler
Kein Leerzeichen nach der Überschrift
#Überschrift wird nicht erkannt, verwenden Sie # Überschrift (Leerzeichen nach #).
Falsche Listeneinrückung
Teillisten müssen um 2 oder 4 Leerzeichen eingerückt werden (je nach Parser). Falsche Einrückung verhindert die Anzeige von Teillisten.
Nicht geschlossener Codeblock
### Sonderzeichen nicht maskiert
Um Symbole wie * oder # anzuzeigen, \ davorsetzen zur Maskierung: \* zeigt *.
### Tabellensyntaxfehler
Eine Tabelle braucht eine Trennzeile für den Kopf (| --- |). Ohne diese wird sie nicht als Tabelle erkannt.
### Unbalancierte Linkklammern
`[Link](url` ohne schließende Klammer, der Link wird nicht erkannt.
## Bewährte Methoden
### Ein Dokument, ein Thema
Ein Artikel behandelt ein Thema. Bei mehreren Themen in mehrere Artikel aufteilen und per Links verknüpfen.
### Erst Inhalt, dann Formatierung
Zuerst den Klartext schreiben, dann Markdown-Tags hinzufügen. Vermeiden Sie Anpassungen beim Schreiben, das unterbricht den Gedankenfluss.
### Einheitlicher Stil
Das Schreibteam sollte den Stil vereinheitlichen:
- Wie viele Überschriftsebenen
- Listen mit - oder *
- Sprachangabe bei Codeblöcken
- Maximale Verschachtelungstiefe von Listen
### Quelldatei behalten
Markdown ist die Quelldatei, HTML/PDF sind generierte Produkte. Markdown behalten für einfache Änderungen, Ausgabeformate jedes Mal neu generieren.
## Zusammenfassung
Essenz des Markdown-Schreibens: klare Überschriftenhierarchie, prägnante Absätze, gute Nutzung von Listen, Code mit Sprachangabe, Bildbeschreibungen. Geeigneten Editor wählen, Stil vereinheitlichen, Quelldatei behalten. Für die Anzeige das [DocsAll Markdown-zu-HTML-Tool](/convert-tools/markdown-to-html) verwenden, läuft im Browser.