Ich habe Markdown seit Jahren jeden Werktag geschrieben - Plugin READMEs, Changelogs, Docs 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 das eine in das andere kompilieren Die Regeln, die Personen aufladen: aufeinanderfolgende Zeilen werden in einen Absatz eingefügt, es sei denn, Sie beenden eine Zeile mit zwei Leerzeichen (oder schalten eine Option & quot; breaks" ein), rohes HTML wird entweder durchgelassen oder entweicht je nach den Vertrauenseinstellungen von parser's, und GitHub's Dialekt (GFM) fügt Tabellen, Aufgabenlisten, Durchstreichen und bare-URL-Autolinking oben auf dem hinzu gebräuchliche Marke Basislinie. Eingezäunter Code kompiliert zu
<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 Klartextsyntax, die John Gruber 2004 veröffentlichte, mit einem erklärten Designziel: Ein Markdown-Dokument soll so veröffentlichbar sein, wie es ist, lesbar als Klartext, ohne auszusehen, als wäre es mit Tags markiert worden Deshalb lehnt sich die Syntax an die Konventionen an, die Menschen bereits in E-Mails verwendet haben - Sternchen um ein Wort zur Hervorhebung, eine Zeile von Strichen 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 Markdown gerendert - GitHub, eine statische Site, ein Docs-Portal, eine Chat-App - führte zuerst einen Parser aus und legte HTML auf den Bildschirm.
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 Markdown mit GitHub-Geschmack?
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 identische Ausgaben für dieselbe Eingabe erzeugen Es definiert die Basislinie - Überschriften, Absätze, Hervorhebung, Links, Bilder, Listen, Blockquotes, Codeblöcke, thematische Brüche, 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 beim Rendern durch den Browser auf ein Leerzeichen zusammenklappt. Es ist kein Fehler; Es handelt sich um die Spezifikation, und sie existiert, sodass Sie Ihre Prosa in 80 Spalten in einem Texteditor fest umwickeln können, ohne dass diese Umhüllung in die Ausgabe gelangt.
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 einen harten Bruch erzeugen -
<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 Originalspezifikation besagt ausdrücklich, dass jedes von Ihnen geschriebene HTML direkt durchläuft. Das ist eine Funktion, wenn Sie der Autor sind (Sie möchten Ihr <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:...">. Ein Kommentarfeld, eine Biografie mit Benutzerprofilen, ein öffentliches Wiki - überall dort, wo Fremde Markdown schreiben, das andere Leute lesen - müssen entweder HTML entkommen oder die Ausgabe mit einem echten Desinfektionsmittel bereinigen (DOMPurify ist die übliche Antwort und es ist gerade deshalb ein echtes Desinfektionsmittel 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 vor dem Rendern - eine Tiefenverteidigung, also jemand anderen einfügen's README in den Vorschauflächen kann seinen Code nicht ausführen. Das ist eine Vorschausicherheitsmaßnahme, kein Allzweck-Desinfektionsmittel: Wenn Sie ein Produkt erstellen, das Benutzer Markdown rendert, verwenden Sie einen dedizierten Desinfektionsmittelserver und vertrauen Sie keinem Regex, einschließlich meines.
Wenn Sie einem Charakter entkommen müssen aus Markdown, damit es wörtlich rendert - ein Sternchen, das ein Sternchen bleiben sollte, ein Unterstrich in einem Dateinamen - ein Backslash macht 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?
Semantisches, langweiliges, klassenfreies 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-Saite -
```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 ein README, ein Changelog, Release Notes, einen Entwurf ein. Ausgabeaktualisierungen während der Eingabe - es gibt keinen Konvertierungsbutton 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 ablegen möchten.
Schritt 3: Überprüfen Sie die Vorschau
Wechseln Sie auf die Vorschau-Registerkarte und bestätigen Sie die Struktur Die Statistikzeile sagt Ihnen Wörter, Überschriften, Links, Bilder, Codeblöcke und Lesezeit - praktisch zum Überprüfen eines Beitrags ist die Länge, die Sie dachten, es wäre, bevor Sie ihn veröffentlichen 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 Markdown-verschachtelte Liste, die mit jedem Überschriftenanker verknüpft ist und am Anfang Ihres Dokuments wieder eingefügt werden kann.
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 in Markdown entwerfen - und die meisten Leute, die regelmäßig schreiben - ist 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 einen Mitwirkenden ein' s Markdown, schauen Sie sich das ausgestrahlte HTML an, und Sie können sofort sehen, ob sie echte Überschriften verwendet oder eine Zeile fett gedruckt haben, um eine zu fälschen - eine Gewohnheit, die die Dokumentstruktur und Zugänglichkeit zerstört Bildschirmleser navigieren nach Ü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 handelt sich um einen handgeschriebenen Parser mit etwa 400 Zeilen und ohne Abhängigkeiten - was bewusst ist, denn ein Markdown-Parser, der eine 200-KB-Abhängigkeit in eine Seite zieht, deren Sinn darin besteht, schnell zu sein, ist ein schlechter Handel.
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 das HTML erscheint sofort - es gibt keinen Konvertierungsbutton und keine Datei zum Hochladen Schalten Sie GitHub Flavored Markdown ein, wenn Ihre Quelle Tabellen oder Aufgabenlisten verwendet, kopieren Sie dann den HTML-Code oder laden Sie ihn als html-Datei herunter. Alles läuft in Ihrem Browser, sodass 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 ist das Verhalten, das GitHub-Kommentare und die meisten Chat-Apps verwenden, aber es ist nicht das, 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> Wird als wörtlicher Text und nicht als Tag angezeigt Schalten Sie die Option tlow-raw-HTML ein, um Tags direkt durchzugehen, was Sie wollen, wenn Ihr Markdown bewusst HTML einmischt - 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 ist standardmäßig entgangen, und die Live-Vorschau streift zusätzlich Skript - und Style-Tags, Inline-Event-Handler und Javascript: URLs vor dem Rendern, nichts, was Sie einfügen, wird irgendwo übertragen Wenn Sie ein Produkt erstellen, das Markdown von Fremden rendert, verwenden Sie dennoch einen dedizierten Desinfektionsmittel wie DOMPurify serverseitig - 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, Hervorhebung, Links, Bilder, Autolinks, Blockquotes, verschachtelte und lose Listen, eingezäunter und eingerückter Code, thematische Brüche, Backslash-Escapes - plus die GFM-Erweiterungen Links im Referenzstil, Fußnoten und einige seltene CommonMark HTML-Block Edge Cases werden nicht behandelt Für bitgenaue Konformität in einer Build-Pipeline verwenden Sie Markdown-it, Remark 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
