Markdown zu HTML: ein sauberer Veröffentlichungs-Workflow

Eine Veröffentlichungs-Pipeline braucht ein Master-Format, das Werkzeuge, Hoster und Redesigns überlebt. Klartext-Markdown ist dieser Master: in jedem Editor lesbar, in der Versionskontrolle diffbar und unabhängig davon, welches HTML-Template es dieses Jahr rendert.

Die Disziplin, die das funktionieren lässt, ist Einwegfluss: Markdown wird von Hand bearbeitet, HTML vom Konverter erzeugt, und niemand patcht die Ausgabe manuell. In dem Moment, in dem exportiertes HTML Handänderungen bekommt, gibt es zwei Master – und sie werden auseinanderdriften.

• PortabelPortabilität: Eine Markdown-Datei öffnet in jedem Editor und konvertiert ohne Migrationsprojekt zu HTML, PDF, Folien oder einem Dokumentationssystem.
• DiffbarReviewbarkeit: Prosa-Änderungen erscheinen als saubere Zeilen-Diffs, während ein HTML-Master eine Ein-Wort-Änderung in Tags und Attributen vergräbt.
• Struktur, nicht StilTrennung der Zuständigkeiten: Die Quelle trägt Struktur – Überschriften, Listen, Zitate –, während das Theme die Typografie entscheidet, sodass ein Redesign das Archiv nie anfasst.

Bewusste Konverter unterstützen absichtlich eine Teilmenge, denn jedes unterstützte Konstrukt ist ein weiterer Weg, Markup einzuschmuggeln, das niemand geprüft hat. Wisse, wo dein Inhalt relativ zu dieser Linie liegt, bevor du dich auf die Konvertierung verlässt.

Im Modus Markdown zu HTML bleibt bei Bildsyntax nur der Alternativtext erhalten, nicht das Bild oder seine URL; rohes HTML wird als Text maskiert. Im Modus HTML zu Markdown wird eine eingefügte Tabelle zu einem abgegrenzten Textblock und verliert ihr Raster. Prüfe das konvertierte Ergebnis vor der Veröffentlichung.

• Saubere KonvertierungenKonvertiert sauber: Überschriften bis sechs Ebenen, Absätze, fett, kursiv, durchgestrichen, Inline-Code, abgezäunte Codeblöcke, geordnete und ungeordnete Listen, Blockzitate, horizontale Linien und Inline-Links.
• Bekannte VerlusteAußerhalb der unterstützten Teilmenge hängt das Ergebnis von der Richtung ab: Markdown-Bildsyntax behält nur den Alternativtext, rohes HTML in Markdown wird als Text maskiert, und HTML-Tabellen werden beim Rückweg zu Markdown zu abgegrenzten Textblöcken. Prüfe Fußnoten und Aufgabenlisten im Ergebnis, statt ihr Überleben vorauszusetzen.
• Einen echten Artikel testenDer Test ist einfach: Konvertiere einen repräsentativen Artikel und lies die Ausgabe. Was im Ergebnis fehlt, war nie Teil des Vertrags.

Konvertiertes HTML kann in eine Seite eingefügt werden; deshalb bereinigt der Arbeitsbereich es standardmäßig. Aktive Elemente werden entfernt, unbekannte Tags zu Text entpackt und Attribute gestrichen – mit Ausnahme zulässiger Link-URLs und gültiger Startwerte nummerierter Listen.

Der Vorschaubereich rendert die sanitisierte Ausgabe und lädt nie entfernte Ressourcen, selbst das Einfügen feindlichen Markups kann das Tool also nicht nach Hause telefonieren lassen.

• Aktive Inhalte entferntElemente mit aktivem Verhalten – script, style, iframe, object, embed, svg, form, video, audio, img – werden samt Inhalt entfernt, nicht bloß neutralisiert.
• Attribute abgestreiftInline-Stile, Event-Handler und Klassen aus der Quelle werden entfernt. Sichere Links behalten href, gültige nummerierte Listen behalten start.
• Gemeldet, nicht stillDer Arbeitsbereich meldet, was er entfernt hat – Zählungen verworfener Knoten und abgestreifter Attribute –, Sanitisierung ist also ein sichtbares Ereignis, keine stille Mutation.

Ein gerendertes Dokument besteht größtenteils aus Links, und Links sind die Stelle, an der Sanitisierung konkret wird. Der Konverter akzeptiert http-, https- und mailto-URLs plus seiteninterne #fragmente; alles andere – javascript:, data:, protokoll-relative Tricks – verliert sein href und rendert als Klartext.

Prüfe die Allowlist gegen deinen Inhalt, bevor du dich auf einen Konverter standardisierst: Eine Dokumentation, die legitim auf FTP-Mirror oder eigene Anwendungsschemata verlinkt, braucht diese Links per Hand bewahrt, denn kein vernünftiger Sanitizer lässt sie automatisch durch.

• Schema-AllowlistÜberlebende Links werden mit rel="noreferrer noopener" gestempelt, ein gefolgter Link kann die Seite, von der er geöffnet wurde, also weder sehen noch skripten.
• noopener noreferrerDieselbe Regel gilt in beide Richtungen: In Markdown geschriebene Links werden bei der Konvertierung geprüft, und in eingefügtem HTML gefundene hrefs werden nach der Sanitisierung erneut geprüft.
• Linktexte überlebenWenn ein Link sein Schema verliert, bleibt der Linktext – defekte Navigation ist sofort sichtbar, statt eine stille javascript:-Nutzlast auszuliefern.

Die Umwandlung von HTML in Markdown dient der Wiedergewinnung, nicht einem verlustfreien Roundtrip. Unterstützte Überschriften, Absätze, Hervorhebungen, Listen, Zitate und Code kehren als Markdown zurück. Andere Strukturen können bei Bereinigung und Umwandlung vereinfacht oder entfernt werden.

Behandle HTML-zu-Markdown als Weg, Prosa aus einer Seite zu ziehen, die du nicht mehr kontrollierst – ein alter CMS-Export, ein Dokument, das nur als gerendertes HTML existiert. Repariere dann, was der Roundtrip nicht kann: Füge die Bilder wieder hinzu, baue die Tabellen neu, und führe von da an das Markdown als Master.

• Tabellen kollabierenTabellen verlieren ihr Raster und werden zu einem abgegrenzten Textblock; tabellarische Daten müssen daher neu erstellt oder als CSV exportiert werden.
• Medien sind entferntBilder, Videos und interaktive Einbettungen sind per Design weg – der Sanitizer hat sie als aktive Inhalte entfernt, bevor das Markdown gebaut wurde.
• Text überlebt StylingFormatierung außerhalb der Teilmenge – spans, divs, Klassen, Ankerziele – hinterlässt keine Spur; der Text überlebt, die Darstellung nicht.

Der Konvertierungsschritt läuft zur Veröffentlichungszeit, einmal pro Artikel: In Markdown entwerfen und reviewen, zu sanitisiertem HTML konvertieren, das gerenderte Ergebnis verifizieren und ausliefern. Alles passiert im Browser-Tab – der Entwurf wird nie hochgeladen, was zählt, wenn der Inhalt ein unangekündigter Launch ist.

• Schritt zur VeröffentlichungszeitDer Arbeitsbereich akzeptiert bis zu 256 KiB Quelltext und erzeugt bis zu 512 KiB Ausgabe – komfortabel Buchkapitel-Maßstab – und meldet jenseits dieser Grenzen einen expliziten Fehler statt stiller Kürzung.
• Explizite GrenzenKopiere die Ausgabe in dein CMS-Feld oder lade sie als Datei herunter; beide Wege nehmen dasselbe sanitisierte Dokument, das dir die Vorschau gezeigt hat.
• Neu konvertieren, nicht patchenHalte das Markdown in der Versionskontrolle neben dem Code, den es dokumentiert, und konvertiere nach jeder Änderung neu, statt altes HTML zu patchen.