Markdown zu HTML: Syntaxzuordnung und Stilbehandlung

Warum Markdown zu HTML

Markdown ist eine schreiberfreundliche, leichtgewichtige Auszeichnungssprache, aber der Browser versteht nur HTML. In Markdown geschriebener Inhalt muss nach HTML konvertiert werden, um im Web angezeigt zu werden.

Häufige Szenarien:

• Veröffentlichung von Blogartikeln
• Rendern von Dokumentationsseiten
• README anzeigen
• Rich-Text-Editoren geben HTML aus

Syntaxzuordnung zwischen Markdown und HTML

Überschriften

Markdown:

# Überschrift Ebene 1
## Überschrift Ebene 2
### Überschrift Ebene 3

HTML:

<h1>Überschrift Ebene 1</h1>
<h2>Überschrift Ebene 2</h2>
<h3>Überschrift Ebene 3</h3>

Absatz

Markdown: Textblöcke getrennt durch Leerzeilen. HTML: <p>Absatz</p>

Hervorhebung

Markdown:

**fett**
*kursiv*
~~durchgestrichen~~

HTML:

<strong>fett</strong>
<em>kursiv</em>
<del>durchgestrichen</del>

Links

Markdown:

[Linktext](https://example.com)

HTML:

<a href="https://example.com">Linktext</a>

Bilder

Markdown:

![Alternativtext](image.png)

HTML:

<img src="image.png" alt="Alternativtext">

Listen

Markdown ungeordnete Liste:

- Eintrag 1
- Eintrag 2

HTML:

<ul>
  <li>Eintrag 1</li>
  <li>Eintrag 2</li>
</ul>

Markdown geordnete Liste:

1. Erster Eintrag
2. Zweiter Eintrag

HTML:

<ol>
  <li>Erster Eintrag</li>
  <li>Zweiter Eintrag</li>
</ol>

Code

Markdown Inline-Code:

Das ist `code` inline

HTML: Das ist <code>code</code> inline

Markdown Codeblock:

Codeblock

HTML:

<pre><code>Codeblock</code></pre>

Mit Sprach-Highlighting:

const x = 1;

Nach der Konvertierung sind Highlighting-Markierungen enthalten (eine Highlighting-Bibliothek wird vorausgesetzt).

Zitat

Markdown:

> Das ist ein Zitat

HTML:

<blockquote>Das ist ein Zitat</blockquote>

Trennlinie

Markdown:

---

HTML:

<hr>

Tabellen

Markdown:

| Name | Alter |
| ---- | ----- |
| Tom  | 25    |

HTML:

<table>
  <thead>
    <tr><th>Name</th><th>Alter</th></tr>
  </thead>
  <tbody>
    <tr><td>Tom</td><td>25</td></tr>
  </tbody>
</table>

Erweiterte Syntax

Standard-Markdown (CommonMark) enthält die folgenden Funktionen nicht, aber die meisten Parser unterstützen sie:

Aufgabenlisten

- [x] Erledigt
- [ ] Nicht erledigt

HTML:

<ul>
  <li><input type="checkbox" checked disabled> Erledigt</li>
  <li><input type="checkbox" disabled> Nicht erledigt</li>
</ul>

Fußnoten

Text[^1]

[^1]: Fußnoteninhalt

Durchgestrichen

~~durchgestrichen~~

Automatische Links

URLs werden automatisch in Links umgewandelt (ohne manuelles ).

Definitionslisten, Inhaltsverzeichnisse, Formeln usw.

Werden von einigen Parsern unterstützt, die Kompatibilität variiert.

Hinweise zur Konvertierung

Stil geht verloren

Markdown zu HTML erzeugt nur Tags, ohne Stile. Die Darstellung hängt vom CSS ab:

• Größe und Abstand der Überschriften
• Einrückung und Zeichen der Listen
• Hintergrund und Schriftart der Codeblöcke
• Rahmen der Tabellen

Nach der Konvertierung CSS hinzufügen, damit es gut aussieht.

XSS-Sicherheit

Markdown erlaubt eingebettetes HTML. Bei der Konvertierung von benutzereingegebenem Markdown in HTML bleiben eingebettete Tags wie <script> erhalten und können XSS verursachen.

Sichere Vorgehensweise:

• Nur reines Markdown verwenden (eingebettetes HTML deaktivieren)
• Nach der Konvertierung in HTML gefährliche Tags mit einer Sanitize-Bibliothek filtern
• Nur Markdown aus vertrauenswürdigen Quellen zulassen

Escape-Zeichen

Sonderzeichen in Markdown (, #, _, ) müssen escaped werden. In Markdown \* schreiben, um ein Sternchen anzuzeigen; nach der HTML-Konvertierung ist es ` und kein Tag.

Bildpfade

Bilder mit relativen Pfaden in Markdown behalten nach der HTML-Konvertierung den Pfad. Bei Verzeichniswechsel Pfad anpassen.

Anker-Links

Markdown-Überschriften erzeugen automatisch Anker (id). Die Regeln unterscheiden sich je nach Parser, beim Setzen von Anker-Links aufpassen.

Konvertierungswerkzeuge

Online-Konvertierung

Markdown einfügen, das Werkzeug gibt HTML aus. Geeignet für einmalige Konvertierungen.

Mit dem Markdown-zu-HTML-Werkzeug:

1. Markdown-Inhalt einfügen
2. Werkzeug analysiert und konvertiert
3. HTML-Code ausgeben
4. Kopieren und verwenden

Konvertierung im Browser, Inhalt wird nicht hochgeladen.

Editor-Integration

VS Code, Typora und andere Editoren haben eine integrierte Markdown-zu-HTML-Vorschau.

Programmatische Konvertierung

In JavaScript die Bibliotheken marked, markdown-it verwenden. In Python die Bibliotheken markdown, mistune.

Konvertierungstipps

Markdown-Stil vereinheitlichen

Unterschiedliche Markdown-Dialekte (CommonMark, GFM, MDX) können unterschiedliche Ergebnisse liefern. Das Team sollte sich auf einen Dialekt einigen.

Vorschau-Validierung

Nach der Konvertierung im Browser prüfen:

• Überschrifthierarchie korrekt?
• Listenverschachtelung normal?
• Codeblöcke gehighlightet?
• Tabellen ausgerichtet?
• Bilder sichtbar?
• Links klickbar?

Passendes CSS

Ein Markdown-Rendering-CSS bereithalten und auf das konvertierte HTML anwenden, dann sieht es gut aus.

Original-Markdown behalten

HTML ist das Rendering-Ergebnis, Markdown die Quelldatei. Markdown behalten für spätere Bearbeitung, HTML jedes Mal neu erzeugen.

Häufige Fragen

Stil nach Konvertierung falsch

HTML hat kein CSS. Eine Markdown-Rendering-Stylesheet hinzufügen.

Codeblöcke nicht gehighlightet

Eine Syntax-Highlighting-Bibliothek ist nötig (z. B. highlight.js, Prism). Ob das Konvertierungswerkzeug Highlighting integriert hat, hängt von der Konfiguration ab.

Tabelle verschoben

Die Markdown-Tabellensyntax ist nicht streng (Spaltenzahl stimmt nicht). Vor der Konvertierung das Tabellenformat prüfen.

Sonderzeichen werden falsch angezeigt

Die Zeichen < > & haben in HTML eine besondere Bedeutung. Sie müssen als < > & escaped werden.

Zusammenfassung

Markdown zu HTML hat als Kern die Syntaxzuordnung. Achten Sie auf passendes CSS, XSS-Sicherheit und das Escaping von Sonderzeichen. Das DocsAll Markdown-zu-HTML-Werkzeug läuft im Browser, der Inhalt bleibt lokal.