Ich habe seit Jahren jeden Arbeitstag einen Abschlag geschrieben - Plugin-Readmes, Changelogs, Dokumente für toolz.dev, Release Notes für WP Adminify, die Hälfte meiner Commit-Nachrichten. Und die meiste Zeit habe ich den Renderschritt als Magie behandelt. Sie schreiben Sternchen, GitHub zeigt mutig. subtil weitermachen.
Dann erstellte ich einen Dokumentabschnitt, der die Datenbank auszeichnete und in eine Seite next.js renderte, und die Magie wurde zu einer Liste sehr spezifischer Entscheidungen, die ich treffen musste. Wird eine einzelne Zeilenzeile a <br>? (GitHub-Kommentare sagen ja. Die Markdown-Spezifikation sagt Nein.) tut <div> in der Quelle als Div oder als wörtlicher Text? (Hängt ab, wer fragt und ob Sie dem Autor vertrauen.) Welche Klasse spielt sich auf einem eingezäunten Codeblock, sodass der Textmarker ihn aufnimmt? Warum dreht sich ein Parser? **bold**text in Fett und ein anderer lässt es in Ruhe?
Nichts davon ist exotisch. Es ist nur das Zeug, das dir niemand sagt, denn Markdown sieht so einfach aus, dass die Leute annehmen, dass nichts darunter ist. Darunter steckt ziemlich viel. der Markdown auf HTML Konverter auf toolz.dev stellt diese Entscheidungen als Switches dar, anstatt sie zu verbergen. Dies ist die Version dieses Tools, die ich beim Debuggen wollte, warum meine Zeilenumbrüche immer wieder verschwanden.
tl; dr: Markdown ist ein Schreibformat, HTML ist das Anzeigeformat. Etwas muss in das andere kompiliert werden. Die Regeln, die Menschen auslösen: Aufeinanderfolgende Zeilen verbinden sich in einem Absatz, es sei denn, Sie beenden eine Zeile mit zwei Leerzeichen (oder aktivieren eine Option "Brüche"), wird abhängig von den Vertrauenseinstellungen des Parsers, und Githubs Dialekt (GFM) Tabellen, Aufgabenlisten, Durchstreichungen und nackte Autolinks auf der CommonMark-Baseline hinzugefügt. Eingezäunter Code wird zu kompiliert
<pre><code class="language-js">, das ist das Hook Prisma, Highlight.js und Shiki suchen. der Markdown in HTML-Konverter Das alles in Ihrem Browser, bei jedem freigegebenen Switch.
Was ist Markdown und warum muss es überhaupt konvertiert werden?
Markdown ist eine Klartext-Syntax, die John Gruber 2004 veröffentlichte, mit einem erklärten Designziel: Ein Markdown-Dokument sollte unveröffentlicht sein, als Nur-Text lesbar, ohne so aussehen, als wäre es mit Tags markiert worden. Aus diesem Grund entlehnt die Syntax die Konventionen, die bereits in E-Mails verwendet wurden - Sternchen um ein Wort für Hervorhebung, eine Zeile unter einer Überschrift, a > für ein Zitat.
Die Folge ist, dass Markdown kein Rendering-Format ist. Nichts zeigt einen Markdown. Browser zeigen HTML und jeden Ort an, den Sie jemals haben erblickt Rendered - GitHub, eine statische Website, ein Dokumentenportal, eine Chat-App - hat zuerst einen Parser ausgeführt und HTML auf den Bildschirm gestellt.
Die Umstellung muss also irgendwo erfolgen. Ihre Möglichkeiten sind ungefähr:
- Zur Bauzeit, in einem statischen Standortgenerator oder Bundler. Gut, wenn der Inhalt in Ihrem Repo lebt.
- auf Anfrage Zeit, auf einem Server. Erforderlich, wenn Inhalte aus einer Datenbank stammen, kostspielig, wenn Sie dies bei jeder Anfrage ohne Caching tun.
- Im Browser, im Moment brauchst du es. Das ist, was Sie wollen, wenn die Antwort auf "Ich brauche nur das HTML für diese eine Sache" eine Kopier-Einfügung und keine Build-Pipeline ist.
Dieser dritte Fall ist häufiger als es klingt. Einfügen von Release-Notizen in ein CMS-Feld, das nur HTML benötigt. Ein Readme in eine E-Mail-Vorlage erhalten. Überprüfen Sie, wie ein Dokument aussehen wird, bevor Sie es festlegen. Umwandeln eines in Obsidian geschriebenen Entwurfs in etwas, das Sie einem Designer übergeben können. Keiner von ihnen rechtfertigt die Verkabelung eines Parsers in ein Projekt.
Was ist der Unterschied zwischen CommonMark und GitHub-Aroma?
Die ursprüngliche Spezifikation von Gruber war eine Seite mit Prosa und ein Perl-Skript, und es ließ genug Unklarheiten, dass jede Implementierung in den Edge-Fällen nicht einverstanden war. gebräuchliche Marke ist die Antwort darauf: eine strenge, überprüfbare Spezifikation mit einer Konformitätssuite von Hunderten von Beispielen, so dass zwei konforme Parser für denselben Eingang eine identische Ausgabe erzeugen. Es definiert die Basislinie - Überschriften, Absätze, Betonung, Links, Bilder, Listen, Blockzitate, Codeblöcke, thematische Unterbrechungen, Backslash-Escapes, HTML-Blöcke.
GitHub-Aromat-Markdown (GFM) ist eine formale Obermenge von CommonMark, die von GitHub angegeben wird, die die Dinge hinzufügt, nach denen die Leute immer wieder gefragt haben:
| Feature | gebräuchliche Marke | GBM | Satzsprache |
|---|---|---|---|
| Tische | kein | ja | | a | b | Mit einem | --- | --- | Trennzeichen |
| Aufgabenliste | kein | ja | - [x] done / - [ ] todo |
| durchschlagen | kein | ja | ~~gone~~ |
| Auto verlinkte nackte URLs | kein | ja | https://toolz.dev Ohne Klammern |
| Fußnoten | kein | Ja (GitHub-Erweiterung) | [^1] |
| Überschriften, Listen, Code, Hervorhebung | ja | ja | ident |
Wenn Ihr Markdown von einer GitHub-Readme, einem Gitlab-Wiki, einem Begriffsexport oder den meisten modernen Editoren stammt, ist es GFM. Schalten Sie GFM im Konverter ein oder Ihre Tabellen werden als buchstäbliche Rohre gerendert. Dies ist die Nummer eins. "Der Konverter ist kaputt" Support-Frage Jeder, der eines dieser Werkzeuge aussendet, erhält.
Warum ist mein Zeilenumbruch verschwunden?
Da Markdown nach den Konventionen von Klartext-E-Mails konsekutive, nicht leere Zeilen als einen einzigen Absatz behandelt. das:
Line one
Line two
Erzeugt <p>Line one\nLine two</p> — Ein Absatz, und die neue Zeile wird in einem Leerzeichen zusammengebrochen, wenn der Browser ihn rendert. Es ist kein Fehler, es ist die Spezifikation, und es existiert, so dass Sie Ihre Prosa in 80 Spalten in einem Texteditor fest umwickeln können, ohne dass diese Verpackung in die Ausgabe eindringt.
Es gibt drei Möglichkeiten, eine aktuelle Pause zu bekommen:
- Eine Leerzeile Startet einen neuen Absatz. Das ist es, was Sie die meiste Zeit wollen.
- Zwei Trailing-Räume Am Ende einer Linie eine harte Pause machen -
<br />drohen Dies ist der Standardtrick, der in Ihrem Editor unsichtbar ist, weshalb die Leute ihn als verrückt empfinden. - Ein Rückstrich Am Ende der Linie macht das gleiche in CommonMark und ist zumindest sichtbar.
Und dann ist da noch der vierte Weg, der die Quelle der Verwirrung ist: Viele Plattformen schalten einen "Breaks" -Modus ein wo jede einzelne Zeile zu einem wird <br />drohen GitHub Kommentare und Probleme tun dies. Die meisten Chat-Apps tun dies. GitHub Readme-Dateien nichtdrohen Der gleiche Text wird also in einem GitHub-Problem und in der Readme des gleichen Repositorys anders gerendert, was ein wirklich schlechtes Stück Design ist, mit dem wir jetzt alle festhalten.
Der Konverter stellt dies als Schalter frei. Wenn Ihre Quelle für einen Renderer im Chat-Stil geschrieben wurde, aktivieren Sie Zeilenumbrüche. Wenn es sich um ein Dokument handelt, lassen Sie es aus und verwenden Sie leere Zeilen, wie es die Spezifikation beabsichtigt.
Wie wird RAW-HTML behandelt?
Markdown erlaubt Inline-HTML - Die ursprüngliche Spezifikation besagt explizit, dass jeder HTML-Code, den Sie schreiben, direkt durchgeht. Das ist eine Funktion, wenn Sie der Autor sind (Sie wollen Ihre <details> Block, dein <img> mit einem Breitenattribut, Ihr Anker mit a rel), und es ist eine Haftung, wenn Sie nicht sind.
Denn wenn Sie nicht vertrauenswürdigen Markdown mit aktiviertem HTML-Pass-Through-Rendering rendern, haben Sie eine XSS-Sicherheitssicherheit. <script>alert(document.cookie)</script> ist gültiger Abschlag. so ist <img src=x onerror="...">drohen So ist ein <a href="javascript:...">drohen Ein Kommentarfeld, eine Benutzerprofil-Biografie, ein öffentliches Wiki - überall, wo Fremde einen Markdown schreiben, den andere Leute lesen - muss entweder HTML entkommen oder die Ausgabe mit einem echten Desinfektionsmittel desinfizieren (Dompurify ist die übliche Antwort und es ist ein echter Desinfektionsmittel, gerade weil ein Regex für eine feindliche Eingabe nicht ausreicht).
Dieser Konverter ist standardmäßig entkommen Rohes HTML: <div> In Ihrer Quelle wird als wörter Text angezeigt <div> In der Ausgabe genau so, als hättest du geschrieben <div>drohen Sie können Pass-Through einschalten, wenn die Quelle Ihnen gehört. Und unabhängig von dieser Einstellung zieht sich die Live-Vorschau <script>, <style>, Inline on* Event-Handler und javascript: URLs, bevor es gerendert wird - Eine vertiefte Verteidigung, sodass das Einfügen einer anderen Readme-Datei in das Vorschaufenster nicht ausgeführt werden kann. Dies ist eine Vorschau-Sicherheitsmaßnahme, kein Allzweck-Desinfektionsmittel: Wenn Sie ein Produkt erstellen, das Benutzer markdown leistet, verwenden Sie einen dedizierten Desinfektionsgerät auf Serverseite und vertrauen Sie einem Regex nicht, einschließlich meiner.
Wenn Sie einem Charakter entkommen müssen aus Markdown, damit es wörtlich rendert - ein Sternchen, das ein Sternchen, ein Unterstrich in einem Dateinamen bleiben sollte - ein Backslash tut es: \*not emphasis\*drohen Und wenn Sie sich in die andere Richtung streiten, HTML-Entitäten-Encoder/-Decoder ist das Werkzeug für diesen Job.
Welches HTML sollte ein guter Konverter eigentlich ausgeben?
Semantische, langweilige, klassenfreie HTML – mit einer Ausnahme.
- Überschriften werden
<h1>–<h6>drohen Wenn die Überschrift-IDs aktiviert sind, erhält jeder auch eine Slugificid, dedupliziert, wenn zwei Überschriften einen Titel teilen (#setup,#setup-1).). Das macht#anchorDeep Links funktionieren, und es ist das, was ein Generator für Inhaltsverzeichnisse hängt. - Ein eingezäunter Block mit einer Info-Zeichenfolge —
```js- wird<pre><code class="language-js">drohen *Dies ist die Ausnahme. * * die `Sprache-`Klasse ist das Konventionprisma, Highlight.js und Shiki suchen alle, und deshalb emittiert der Konverter überhaupt eine Klasse. Der Konverter färbt Ihren Code nicht, der Highlighter auf Ihrer Seite und er benötigt diesen Haken. - Listen werden
<ul>/<ol>und hier ist eine subtile Wissenswerte: a stramm Liste (keine Leerzeilen zwischen Elementen) setzt den Text direkt hinein<li>, während ein wackeln Liste (leere Zeilen zwischen Artikeln) umschließt den Inhalt jedes Artikels in<p>drohen Das ist ein Commonmark-Verhalten, keine Eigenart, und deshalb wächst Ihre Liste plötzlich vertikaler Abstand, wenn Sie eine Leerzeile zwischen zwei Aufzählungszeichen hinzufügen. Das CSS ist nicht kaputt, das HTML wirklich geändert. - Tische werden real
<table>/<thead>/<tbody>Aufschlag, mitstyle="text-align:center"auf Zellen, wenn die Trennzeichenzeile verwendet:---:drohen - Aufgabenlisten werden
<input type="checkbox" disabled>im Inneren der<li>, genau das emittiert GitHub.
Inhaltserst, keine Wrapper-Divs, keine Utility-Klassen. Sie stylen es von außen mit einem .prose Klasse oder eigene Regeln, und das Markup bleibt tragbar.
Wie verwende ich den Konverter?
Schritt 1: Fügen Sie den Markdown ein
Geben Sie eine Readme, ein Changelog, Release Notes, einen Entwurf ein. Ausgabeaktualisierungen während der Eingabe – Es gibt keine Schaltfläche "Konvertieren" und es wird nichts hochgeladen.
Schritt 2: Schalter einstellen
GitHub-Geschmack Ein, wenn die Quelle Tabellen, Aufgabenlisten oder Durchgestrichen hat (dies ist wahrscheinlich der Fall). Überschrift IDs auf, wenn Sie Anker wollen. Zeilenumbruch nur wenn die Quelle für einen Chat-Stil-Renderer geschrieben wurde. Erlaube rohen HTML Nur wenn die Quelle Ihnen gehört. Vollständiges Dokument Ein, wenn Sie eine vollständige HTML5-Seite mit doctype, charset, viewport und a <title> genommen von deinem ersten <h1> — Nützlich, wenn Sie das Ergebnis direkt in einem Browser öffnen oder auf einem statischen Host löschen möchten.
Schritt 3: Überprüfen Sie die Vorschau
Wechseln Sie zur Registerkarte Vorschau und bestätigen Sie die Struktur. Die Statistik-Zeile zeigt Ihnen Wörter, Überschriften, Links, Bilder, Codeblöcke und Lesezeit an - praktisch für die Überprüfung eines Beitrags ist die Länge, die Sie für vor der Veröffentlichung gedacht hatten. Für eine gründlichere Zählung ist die Wortzähler Liestability und Keyword-Dichte im selben Text.
Schritt 4: Nehmen Sie die Ausgabe
Kopieren Sie das HTML, laden Sie es als .html Datei oder kopieren Sie das generierte Inhaltsverzeichnis - eine verschachtelte Liste, die mit jedem Überschriftenanker verknüpft ist und bereit ist, oben in Ihr Dokument zurückzufügen.
Wenn Sie das Ergebnis in eine Seite einfügen, auf der Bytes wichtig sind, führen Sie es durch die HTML-Minifire danach Der Ausgang des Konverters ist für die Lesbarkeit eingerückt, nicht für den Draht.
Häufige Anwendungsfälle
Ein Readme auf eine Website bekommen
Plugin- und Paketautoren schreiben eine gute Readme und benötigen dann den gleichen Inhalt auf einer Landing Page. Die Readme ist GFM mit Tabellen und Ausweis, die Landingpage benötigt HTML. Konvertieren, einfügen, stylen Sie mit Ihrem vorhandenen CSS. Die Überschrift-IDs geben Ihnen kostenlos eine Seitenleiste.
Veröffentlichen auf einem CMS, das nur HTML akzeptiert
Viele CMS-Felder, E-Mail-Plattformen und Legacy-Admin-Panels nehmen HTML und sonst nichts. Wenn Sie einen Markdown entwerfen - und die meisten Leute, die regelmäßig schreiben, tun dies die Brücke. konvertieren mit Vollständiges Dokument Aus, also erhalten Sie das Fragment anstelle einer ganzen Seite und fügen es in das Feld ein.
Prototyping einer Dokumentseite
Bevor Sie Inhalte in eine Dokumentenseite übertragen, wird durch die lokale Konvertierung die tatsächliche Überschriftenhierarchie angezeigt und ob Ihre Codezäune die richtige Sprache tragen. ein h3 das hätte ein sein sollen h2 ist im Inhaltsverzeichnis offensichtlich und in der Quelle unsichtbar.
Auditing von Inhalten, die jemand anderes geschrieben hat
Fügen Sie den Markdown eines Mitwirkenden ein, schauen Sie sich den ausgegebenen HTML-Code an und Sie können sofort sehen, ob er echte Überschriften verwendet oder eine Linie zum Fälschen einer Zeile verwendet hat - eine Gewohnheit, die die Dokumentenstruktur und die Barrierefreiheit zerstört. Bildschirmleser navigieren durch Überschrift; **Big Text** ist keine Überschrift, es ist ein fett gedruckter Absatz, und der Konverter zeigt Ihnen dies in einer Ausgabezeile.
Extrahieren eines Inhaltsverzeichnisses
Lange Dokumente brauchen einen, und die Pflege von Hand garantiert, dass es abgestanden wird. Generieren Sie es aus den Überschriften, fügen Sie es ein, regenerieren Sie es, wenn sich die Überschriften ändern.
Fortgeschritten: Was dieser Parser tut und was nicht
Es ist ein handgeschriebener Parser mit ungefähr 400 Zeilen ohne Abhängigkeiten - was absichtlich ist, da ein Markdown-Parser, der eine 200-kB-Abhängigkeit in eine Seite zieht, deren ganzes Ziel schnell ist, ein schlechter Handel ist.
Bedeckt: ATX-Überschriften (# x) und seText Überschriften (unterstrichen mit === / ---), Absätze, Hervorhebung und stark (*, _, **, __), Inline-Code mit Backtick-Run-Matching, eingezäunter Code mit Info-Strings, eingerückten Codeblöcken, Blockzitaten mit faulen Fortsetzung, verschachtelten Listen (bestellt und ungeordnet, eng und lose), thematische Pausen, Links und Bilder mit Titeln, Winkel-Bracket-Autolinks, E-Mail-Autolinks, Backslash-Escapes und der GFM-Set: Tabellen mit Ausrichtung, Aufgabenlisten, Durchstürzen, Bare-Url-Autolinking.
Nicht abgedeckt: Links im Referenzstil ([text][ref] Mit einem [ref]: url Definition an anderer Stelle), Fußnoten, Definitionslisten und einige wirklich obskure CommonMark-Eckfälle um HTML-Blocks, die das Unterbrechen von Absätzen blockieren. Wenn Sie die CommonMark Conformance Suite dagegen ausführen, wird diese nicht 100% bewertet. Wenn Sie eine Readme, einen Changelog oder einen Blog-Beitrag konvertieren, werden Sie es nicht bemerken.
Das ist ein ehrlicher Handel, und das ist der Grund, warum der Konverter sofort geladen wird und mit ausgeschaltetem Netzwerk arbeitet. Verwenden Sie für Content-Pipelines, bei denen Sie die Konformität mit der Bitgenauen CommonMark benötigen markdown-it, remark oder cmark In deinem Build; dafür sind sie da.
FAQ
Wie konvertiere ich Markdown in HTML?
Fügen Sie Ihren Markdown in den Editor ein und der HTML-Code wird sofort angezeigt. Es gibt keine Konvertierungsschaltfläche und keine Datei zum Hochladen. Aktivieren Sie den GitHub-Markdown, wenn Ihre Quelle Tabellen oder Aufgabenlisten verwendet, kopieren Sie den HTML-Code oder laden Sie ihn als HTML-Datei herunter. Alles läuft in Ihrem Browser, so dass unveröffentlichte Entwürfe und interne Dokumente Ihr Gerät niemals verlassen.
Was ist GitHub-Aroma-Markdown?
GitHub Flavored Markdown (GFM) ist eine formal angegebene Obermenge von CommonMark, die Tabellen, Aufgabenlisten-Checkboxen, Durchgestrichen mit Double Tildes und automatische Verknüpfung von nackten URLs hinzufügt. Es ist der Dialekt, der GitHub zum Rendern von Readme-Dateien und -problemen verwendet, und es ist das, was die meisten Markdown-Editoren heute ausgeben. In diesem Konverter ist es standardmäßig aktiviert.
Warum ist mein einzelner Zeilenumbruch verschwunden?
Standard-Markdown verbindet aufeinanderfolgende Zeilen in einem einzigen Absatz; ein Zeilenumbruch überdauert nur, wenn Sie die Linie mit zwei Leerzeichen beenden, einen nachlaufenden Backslash verwenden oder eine Leerzeile hinterlassen. Wenn Sie möchten, dass jede Zeile eine neue Zeile wird <br />, Aktivieren Sie die Option Zeilenumbrüche - das sind die GitHub-Kommentare und die meisten Chat-Apps, die jedoch nicht das tun, was Readme-Dateien tun.
Markiert der Konverter meinen Code?
Es gibt das Markup aus, das ein Highlighter benötigt, färbt aber den Code selbst nicht. Ein eingezäunter Codeblock mit der Sprache markiert js wird <pre><code class="language-js">, das ist das Klassenkonvention Prisma, Highlight.js und Shiki suchen alle. Fügen Sie einer dieser Bibliotheken der Seite hinzu, auf der Sie die Ausgabe einfügen und die Hervorhebung automatisch angezeigt wird.
Wird roher HTML-Code in meinem Markdown beibehalten?
Standardmäßig ist es also entflohen <div> Erscheint eher als wörtlicher Text als als Tag. Aktivieren Sie die Option Allow-raw-html, um die Tags direkt durchzuleiten. Dies ist das, was Sie möchten, wenn Ihr Markdown absichtlich in HTML gemischt wird - a <details> Block oder ein Bild mit Attributen. Aktivieren Sie es nur für die von Ihnen vertrauenswürdige Quelle, da roher HTML-Code eines nicht vertrauenswürdigen Autors ein XSS-Vektor ist.
Ist es sicher, Markdown einzufügen, die ich nicht geschrieben habe?
Ja. HTML wird standardmäßig entweicht, und die Live-Vorschau entfernt zusätzlich Skript- und Stil-Tags, Inline-Ereignishandler und Javascript: URLs vor dem Rendern. Nichts, was Sie einfügen, wird überall übertragen. Wenn Sie ein Produkt erstellen, das Fremden notiert, verwenden Sie dennoch einen speziellen Desinfektionsmittel wie DomPurify server-seitig. Ein Vorschaufilter ist kein Ersatz für einen.
Kann ich aus meinen Überschriften ein Inhaltsverzeichnis generieren?
Ja. Wenn die Überschrift-IDs aktiviert sind, erhält jede Überschrift einen slupfifizierten, de-duplizierten Anker, und das Tool erstellt ein Markdown-Inhaltsverzeichnis, das mit jedem verknüpft ist. Kopieren Sie es wieder in Ihr Dokument und die Links werden gegen die generierten IDs aufgelöst. Erneuern Sie es, wenn sich Ihre Überschriften ändern, anstatt es von Hand zu pflegen.
Implementiert dieser Konverter CommonMark vollständig?
Es implementiert die Konstrukte, die Menschen tatsächlich schreiben - ATX- und Setext-Überschriften, Absätze, Betonung, Links, Bilder, Autolinks, Blockzitate, verschachtelte und lose Listen, eingezäunter und eingerückter Code, thematische Pausen, Backslash-Escapes - sowie die GFM-Erweiterungen. Links, Fußnoten und einige seltene CommonMark-HTML-Block-Edge-Fälle werden nicht behandelt. Verwenden Sie für die bitgenaue Konformität in einer Build-Pipeline MarkDown-it, review oder cMark.
Verwandte Werkzeuge: Markdown auf HTML · HTML-Entitäten · HTML-Minifire · Wortzähler · Schneckengenerator
Verwandte Lektüre: Das Toolkit des Webentwicklers · Handbuch für Textwerkzeuge
