Markdown in HTML umwandeln

Fragment oder Seite – und was Sie brauchen

Es gibt zwei sinnvolle Ausgaben, und sie sind nicht austauschbar. Ein Fragment ist nur das umgewandelte Markup – Überschriften, Absätze, Listen, Links – ohne Dokumentrahmen. Das brauchen Sie, wenn das Ergebnis in eine Vorlage, ein CMS-Feld oder eine andere Seite kommt. Eine vollständige Seite ergänzt Doctype, Head, Zeichensatzdeklaration und Stylesheet, sodass sie sich eigenständig öffnen lässt und nach etwas aussieht. Wer eine vollständige Seite in ein CMS einfügt, erhält ein Dokument im Dokument; wer ein Fragment im Browser öffnet, erhält ungestalteten Text.

Die Umwandlung deckt den weithin anerkannten erweiterten Markdown-Umfang ab: Überschriften, Hervorhebungen, Listen, Links, Bilder, Blockzitate, Tabellen, Codeblöcke mit Syntaxhervorhebung, Aufgabenlisten, Durchstreichen und Fußnoten. Überschriften erhalten aus ihrem Text abgeleitete Kennungen, sodass man direkt auf sie verlinken kann – genau die Ankerlinks, die lange Dokumentationen erst benutzbar machen.

Rohes HTML im Markdown wird durchgereicht. Das gehört zur Spezifikation, und man sollte bewusst damit umgehen: Eine Markdown-Datei aus einer nicht vertrauenswürdigen Quelle kann ein Script-Tag enthalten, und die Umwandlung erzeugt dann eine Seite mit diesem Skript. Rendern Sie Markdown von Fremden nie, ohne das HTML anschließend zu bereinigen – die Umwandlung ist keine Sicherheitsgrenze und war nie als solche gedacht.

Zwei Dinge werden bewusst als Codeblöcke ausgegeben statt dargestellt. Mathematische Formeln in LaTeX-Notation brauchen eine Satzbibliothek, Mermaid-Diagramme einen Diagramm-Renderer – beides sind umfangreiche Abhängigkeiten, und eine falsch dargestellte Gleichung ist schlimmer als eine sichtbare. Eine vollständige Seite nutzt gewöhnliche Systemschriften, statt Schriften nachzuladen. So funktioniert sie offline und sieht unter Windows, macOS und Linux leicht unterschiedlich aus.

Wenn Sie etwas anderes brauchen

Pandoc beherrscht das, was hier fehlt, und vieles mehr: pandoc in.md -o out.html --mathjax --standalone --toc stellt Formeln korrekt dar, erzeugt ein Inhaltsverzeichnis und akzeptiert eine Vorlage, damit die Ausgabe zu Ihrer eigenen Website passt. Außerdem wandelt es in und aus rund vierzig weiteren Formaten um – deshalb lohnt es sich, es einmal zu installieren.

Für eine Website statt einer einzelnen Datei nehmen Sie besser einen Generator, statt Seiten einzeln umzuwandeln. Hugo, Eleventy, Jekyll und MkDocs machen aus einem Ordner voller Markdown eine Website mit Navigation, Suche und einheitlicher Gestaltung und bauen sie bei jeder Änderung der Quelle neu – und genau darum geht es, sobald es mehr als ein Dokument gibt.