J'ai écrit Markdown tous les jours ouvrables pendant des années - Lisez-mes de plug-in, journaux de modifications, docs pour toolz.dev, Notes de version pour WP Adminify, la moitié de mes messages de validation. Et pendant la plupart de ce temps, j'ai traité l'étape de rendu comme magique. Vous écrivez des astérisques, GitHub est en gras. bien. Avancez.
Ensuite, j'ai construit une section de documents qui a retiré la démarque de la base de données et l'a rendue dans une page suivante.js, et la magie s'est transformée en une liste de décisions très spécifiques que je devais prendre. Est-ce qu'un seul nouveauline devient un <br>? (Les commentaires GitHub disent oui. La spécification de démarque dit non) FAIRE <div> Dans le rendu source sous forme de div ou de texte littéral ? (Cela dépend de qui vous demande et si vous faites confiance à l'auteur.) Quelle classe se passe sur un bloc de code clôturé pour que le surligneur le reprenne ? Pourquoi un analyseur tourne-t-il **bold**text dans le gras et un autre le laisse seul ?
Rien de tout cela n'est exotique. C'est exactement ce que personne ne vous dit, car Markdown semble si simple que les gens supposent qu'il n'y a rien en dessous. Il y a beaucoup de choses en dessous. le Markdown en HTML Converter sur Toolz.dev expose ces décisions comme des commutateurs plutôt que de les cacher, ce qui est la version de cet outil que je voulais lorsque je déboguais pourquoi mes sauts de ligne continuaient de disparaître.
tl;dr : Markdown est un format d'écriture, le HTML est le format d'affichage. Quelque chose doit compiler l'un dans l'autre. Les règles qui font trébucher les gens : les lignes consécutives se joignent à un paragraphe, sauf si vous terminez ou échappez une ligne avec deux espaces (ou activez une "option de coupures", HTML brut est transmis ou échappé en fonction des paramètres de confiance de l'analyseur, et le dialecte GitHub (GFM) ajoute des tableaux, des listes de tâches, des barres de base et des liens automatiques de Bare-URL. Le code clôturé se compile
<pre><code class="language-js">, qui est le prisme de crochet, surlignage.js et shiki recherchent. le Convertisseur de Markdown en HTML Fait tout cela dans votre navigateur, avec chaque commutateur exposé.
Qu'est-ce que Markdown et pourquoi doit-il être converti ?
Markdown est une syntaxe en texte brut que John Gruber a publiée en 2004, avec un objectif de conception déclaré : un document Markdown doit être publiable tel quel, lisible en texte brut, sans avoir l'air d'être marqué par des balises. C'est pourquoi la syntaxe emprunte aux conventions que les gens utilisent déjà dans le courrier électronique - astérisques autour d'un mot pour emphase, une ligne de tirets sous une rubrique, un > pour un devis.
La conséquence est que Markdown n'est pas un format de rendu. Rien n'affiche la démarque. Les navigateurs affichent du HTML et chaque endroit que vous avez vu Markdown Rendu - GitHub, un site statique, un portail Docs, une application de chat - a d'abord exécuté un analyseur et mis du HTML à l'écran.
La conversion doit donc avoir lieu quelque part. Vos options sont à peu près :
- Au moment de la construction, dans un générateur de site statique ou un bundler. Bien lorsque le contenu est disponible dans votre référentiel.
- À l'heure de la demande, sur un serveur. Nécessaire lorsque le contenu provient d'une base de données, coûteux si vous le faites sur chaque demande sans mise en cache.
- dans le navigateur, pour le moment, vous en avez besoin. C'est ce que vous voulez lorsque la réponse à "J'ai juste besoin du code HTML pour cette seule chose" est un copier-coller, pas un pipeline de génération.
Ce troisième cas est plus courant qu'il n'y paraît. Coller des notes de version dans un champ CMS qui ne prend que du HTML. Obtenir un fichier de lecture dans un modèle d'e-mail. Vérifier à quoi ressemblera un doc avant de le valider. Convertir un brouillon écrit en obsidienne en quelque chose que vous pouvez confier à un designer. Aucun de ceux-ci ne justifie le câblage d'un analyseur dans un projet.
Quelle est la différence entre Commonmark et Markdown aromatisé à GitHub ?
La spécification originale de Gruber était une page de prose et un script Perl, et cela a laissé suffisamment d'ambiguïté pour que chaque implémentation soit en désaccord sur les cas Edge. marque courante est la réponse à cela : une spécification stricte et vérifiable avec une suite de conformité de centaines d'exemples, de sorte que deux analyseurs conformes produisent une sortie identique pour la même entrée. Il définit la ligne de base - en-têtes, paragraphes, emphase, liens, images, listes, blocs de quotes, blocs de code, sauts thématiques, échappements de barre oblique inverse, blocs HTML.
Markdown aromatisé à GitHub (GFM) est un sur-ensemble formel de Commonmark, spécifié par GitHub, qui ajoute ce que les gens demandent sans cesse :
| figure | marque courante | GFM | syntaxe |
|---|---|---|---|
| tableaux | non | oui | | a | b | avec un | --- | --- | ligne de délimiteur |
| Listes de tâches | non | oui | - [x] done / - [ ] todo |
| percuter | non | oui | ~~gone~~ |
| URL nues auto-liées | non | oui | https://toolz.dev sans crochets |
| notes de bas de page | non | Oui (extension GitHub) | [^1] |
| En-têtes, listes, code, accent | oui | oui | identitaire |
Si votre démarque provenait d'un github readme, d'un wiki Gitlab, d'une exportation de notions ou des éditeurs les plus modernes, c'est GFM. Activez GFM dans le convertisseur ou vos tables seront rendues sous forme de tuyaux littéraux, qui est le numéro un "le convertisseur est cassé" et la question de l'assistance est que l'un de ces outils reçoit.
Pourquoi mon saut de ligne a-t-il disparu ?
Parce que Markdown, suivant les conventions du courrier électronique en texte brut, traite les lignes non vides consécutives comme un paragraphe unique. ceci :
Line one
Line two
produit <p>Line one\nLine two</p> — Un paragraphe, et la nouvelle ligne s'effondre dans un espace lorsque le navigateur le rend. Ce n'est pas un bug, c'est la spécification, et il existe pour que vous puissiez emballer votre prose à 80 colonnes dans un éditeur de texte sans que cette enveloppe fuit dans la sortie.
Il existe trois façons d'obtenir une véritable pause :
- Une ligne vide Démarre un nouveau paragraphe. C'est ce que vous voulez la plupart du temps.
- Deux espaces de fuite Au bout d'une ligne, produit une rupture dure -
<br />. C'est l'astuce standard, et il est invisible dans votre éditeur, c'est pourquoi les gens trouvent cela exaspérant. - Une barre oblique inverse En fin de ligne, fait la même chose dans CommonMark et est au moins visible.
Et puis il y a la quatrième voie, qui est la source de la confusion : De nombreuses plateformes activent un mode "passage" où chaque nouvelle ligne devient un <br />. Les commentaires et les problèmes de GitHub font cela. La plupart des applications de chat le font. Fichiers Lisez-moi GitHub ne pas. Ainsi, le même texte est rendu différemment dans un problème GitHub et dans le fichier Lisez-moi du même référentiel, ce qui est un véritable élément de conception avec lequel nous sommes tous maintenant coincés.
Le convertisseur l'expose comme un commutateur. Si votre source a été écrite pour un rendu de style de chat, activez les sauts de ligne. S'il s'agit d'un document, laissez-le et utilisez des lignes vierges comme le prévoit la spécification.
Comment le code brut brut est-il géré ?
Markdown autorise le code HTML en ligne - la spécification d'origine indique explicitement que tout HTML que vous écrivez passe directement. C'est une fonctionnalité lorsque vous êtes l'auteur (vous voulez que votre <details> bloquer, votre <img> Avec un attribut de largeur, votre ancre avec un rel), et c'est un passif lorsque vous ne l'êtes pas.
Parce que si vous rendez une démarque non fiable avec le transfert HTML activé, vous disposez d'une vulnérabilité XSS. <script>alert(document.cookie)</script> est valide Markdown. Ainsi est <img src=x onerror="...">. Ainsi est un <a href="javascript:...">. Une boîte de commentaires, une bio de profil d'utilisateur, un wiki public - partout où des étrangers écrivent Markdown que d'autres personnes lisent - doivent soit échapper au HTML, soit assainir le résultat avec un véritable désinfectant (Dompurify est la réponse habituelle, et c'est un véritable désinfectant précisément parce qu'un regex n'est pas suffisant pour une entrée hostile).
Ce convertisseur est par défaut évasion HTML brut : <div> dans votre source apparaît comme le texte littéral <div> En sortie, exactement comme si vous aviez écrit <div>. Vous pouvez activer le passage lorsque la source est à vous. Et quel que soit ce paramètre, les bandes de prévisualisation en direct <script>, <style>, en ligne on* Gestionnaires d'événements et javascript: URL avant qu'il ne soit rendu - une défense en profondeur, donc coller le fichier Lisez-moi dans le volet de prévisualisation ne peut pas exécuter leur code. Il s'agit d'une mesure de prévisualisation et de sécurité, et non d'un désinfectant généraliste : si vous créez un produit qui rend l'utilisateur Markdown, utilisez un désinfectant dédié côté serveur et ne faites pas confiance à un regex, le mien inclus.
Si vous devez échapper à un personnage de Markdown pour qu'il rende littéralement - un astérisque qui doit rester un astérisque, un trait de soulignement dans un nom de fichier - une barre oblique inverse le fait : \*not emphasis\*. Et si vous vous disputez dans l'autre sens, le Encodeur/décodeur d'entités HTML est l'outil pour ce travail.
Quel HTML un bon convertisseur devrait-il réellement émettre ?
HTML sémantique, ennuyeux et sans classe, à une exception près.
- Les titres deviennent
<h1>–<h6>. Avec les ID de titre activés, chacun est également unid, doublonné lorsque deux titres partagent un titre (#setup,#setup-1). C'est ce qui fait#anchorLes liens profonds fonctionnent, et c'est ce qu'un générateur de table de contenus accroche. - Un bloc clôturé avec une chaîne d'informations —
```js— devient<pre><code class="language-js">. *C'est l'exception.* * La `langue-` Classe est le prisme de la convention, surlt.js et shiki recherchent tous, et c'est pourquoi le convertisseur émet une classe. Le convertisseur ne colore pas votre code, le surligneur de votre page le fait, et il a besoin de ce crochet. - Les listes deviennent
<ul>/<ol>, et voici une subtilité qui vaut la peine d'être connue : un somm Liste (pas de lignes vides entre les éléments) Met le texte directement à l'intérieur<li>, tandis qu'un aurence Liste (lignes vides entre les éléments) Enveloppe le contenu de chaque élément dans<p>. C'est CommonMark, et non une bizarrerie, et c'est pourquoi votre liste s'accroît soudainement dans l'espacement vertical lorsque vous ajoutez une ligne vide entre deux balles. Le CSS n'est pas cassé, le HTML réellement changé. - Les tableaux deviennent réels
<table>/<thead>/<tbody>balisage, avecstyle="text-align:center"Sur les cellules lorsque la ligne de délimitation utilise:---:. - Les listes de tâches deviennent
<input type="checkbox" disabled>à l'intérieur du<li>, qui est exactement ce qu'émet GitHub.
Content-First, pas de div wrapper, pas de classes d'utilitaires. Vous le coiffez de l'extérieur, avec un .prose classe ou vos propres règles, et le balisage reste portable.
Comment utiliser le convertisseur ?
Étape 1 : Collez la démarque
Déposez un fichier de lecture, un journal des modifications, des notes de version, un brouillon. Mises à jour de sortie que vous tapez — Il n'y a pas de bouton de conversion et rien n'est téléchargé.
Étape 2 : Réglez les commutateurs
GitHub aromatisé ON Si la source a des tableaux, des listes de tâches ou des barrés (c'est probablement le cas). ID de titre Allumé si vous voulez des ancres. sauts de ligne Activé uniquement si la source a été écrite pour un rendu de style de chat. Autoriser le code HTML brut Allumé uniquement si la source est à vous. Document complet sur si vous voulez une page HTML5 complète avec doctype, charset, fenêtre et un <title> Pris de votre premier <h1> — Utile lorsque vous souhaitez ouvrir le résultat directement dans un navigateur ou le déposer sur un hôte statique.
Étape 3 : Vérifiez l'aperçu
Passez à l'onglet Aperçu et confirmez la structure. La ligne des statistiques vous indique des mots, des en-têtes, des liens, des images, des blocs de code et du temps de lecture - pratique pour vérifier un message est la longueur que vous pensiez avant de la publier. Pour un décompte plus approfondi, le compteur de mots Fait la lisibilité et la densité des mots clés sur le même texte.
Étape 4 : Prenez la sortie
Copiez le HTML, téléchargez-le comme .html Fichier ou copiez la table des matières générée - une liste de Markdown imbriquée qui relie à chaque point d'ancrage, prête à coller en haut de votre document.
Si vous collez le résultat dans une page où les octets sont importants, exécutez-le via le minificateur HTML après. La sortie du convertisseur est indentée pour la lisibilité, pas pour le fil.
Cas d'utilisation courants
Obtenir un lisez-moi sur un site Web
Les auteurs du plugin et des packages écrivent un bon fichier de lecture, puis ont besoin du même contenu sur une page de destination. Le Lisez-moi est un GFM avec des tableaux et des badges ; la page de destination a besoin de HTML. Convertissez, collez, stylez avec votre CSS existant. Les identifiants de titre vous donnent gratuitement une table latérale TOC.
Publication sur un CMS qui accepte uniquement le HTML
De nombreux champs de CMS, plateformes de messagerie et panneaux d'administration hérités prennent du HTML et rien d'autre. Si vous rédigez Markdown – et la plupart des gens qui écrivent régulièrement – c’est le pont. se convertir avec Document complet Vous obtenez ainsi le fragment plutôt qu'une page entière et le collez sur le terrain.
Prototypage d'une page de documents
Avant de valider le contenu dans un site Docs, le convertir localement vous montre la hiérarchie des titres et si vos clôtures de code sont assorties du bon langage. un h3 Cela aurait dû être une h2 est évident dans la TOC et invisible dans la source.
Auditer le contenu que quelqu'un d'autre a écrit
Collez la démarque d'un contributeur, regardez le code HTML émis et vous pouvez voir immédiatement s'ils ont utilisé des en-têtes réels ou mis en gras une ligne pour simuler une habitude qui détruit la structure du document et l'accessibilité. Les lecteurs d'écran naviguent par en-tête ; **Big Text** n'est pas un en-tête, c'est un paragraphe en gras, et le convertisseur vous le montre dans une seule ligne de sortie.
Extraction d'une table des matières
Les longs documents en ont besoin, et le maintenir à la main garantit qu'il est rassis. Générez-le à partir des en-têtes, collez-le, régénérez-le chaque fois que les en-têtes changent.
Avancé : ce que fait cet analyseur et ne fait pas
Il s'agit d'un analyseur manuscrit, d'environ 400 lignes, sans dépendances, ce qui est délibéré, car un analyseur de démarque qui attire une dépendance de 200 ko dans une page dont tout le point est rapide est un mauvais échange.
Couvert : En-têtes ATX (# x) et les en-têtes de setext (soulignés avec === / ---), paragraphes, accentuation et fort (*, _, **, __), code en ligne avec correspondance de retour, code clôturé avec chaînes d'information, blocs de code en retrait, blocs de quotes-parts avec continuation paresseuse, listes imbriquées (ordonnées et non ordonnées, étroits et lâches), pauses thématiques, liens et images avec titres, liaisons automatiques angulaires, liaisons automatiques de courrier électronique, backslash, et le jeu GFM : tables avec alignement, listes de tâches, grève, liaison automatique.
Non couvert : Liens de style référence ([text][ref] avec un [ref]: url définition ailleurs), des notes de bas de page, des listes de définitions et quelques cas de coins de Commonmark véritablement obscurs autour des blocs HTML interrompant les paragraphes. Si vous exécutez la suite de conformité CommonMark, elle ne marquera pas 100 %. Si vous convertissez un Lisez-moi, un journal des modifications ou un article de blog, vous ne le remarquerez pas.
C'est un échange honnête, et c'est la raison pour laquelle le convertisseur se charge instantanément et fonctionne avec le réseau désactivé. Pour les pipelines de contenu pour lesquels vous avez besoin de la conformité CommonMark exacte, utilisez markdown-it, remark ou cmark Dans votre construction, c'est pour cela qu'ils sont destinés.
FAQ
Comment convertir Markdown en HTML ?
Collez votre démarque dans l'éditeur et le HTML apparaît immédiatement - il n'y a pas de bouton de conversion et aucun fichier à télécharger. Activez le démarque GitHub Flavored si votre source utilise des tables ou des listes de tâches, puis copiez le code HTML ou téléchargez-le sous forme de fichier .html. Tout fonctionne dans votre navigateur, donc les brouillons non publiés et les documents internes ne quittent jamais votre appareil.
Qu'est-ce que le démarquement aromatisé GitHub ?
GitHub Flavored Markdown (GFM) est un super-ensemble de CommonMark spécifié qui ajoute des tableaux, des cases à cocher de la liste des tâches, du barré avec des doubles tildes et une liaison automatique des URL nues. C'est le dialecte que GitHub utilise pour rendre les fichiers et les problèmes de lecture, et c'est ce que la plupart des éditeurs Markdown émettent aujourd'hui. Il est activé par défaut dans ce convertisseur.
Pourquoi mon break simple ligne a-t-il disparu ?
Le démarquage standard rejoint des lignes consécutives en un seul paragraphe ; un saut de ligne ne survit que si vous terminez la ligne avec deux espaces, utilisez une barre oblique inverse ou laissez une ligne vide. Si vous voulez que chaque nouvelle ligne devienne un <br />, Activez l'option de saut de ligne - c'est le comportement des commentaires GitHub et la plupart des applications de chat utilisées, mais ce n'est pas ce que font les fichiers Lisez-moi.
Le convertisseur met-il en évidence mon code ?
Il émet le balisage dont un surligneur a besoin mais ne colore pas le code lui-même. Un bloc de code clôturé marqué avec la langue js se transforme <pre><code class="language-js">, qui est le prisme de la convention de classe, surlt.js et shiki recherchent tous. Ajoutez une de ces bibliothèques à la page où vous collez la sortie et la mise en surbrillance s'affiche automatiquement.
Le code HTML brut dans mon Markdown est-il conservé ?
Par défaut, il est échappé, donc <div> apparaît comme du texte littéral plutôt que comme une balise. Activez l'option allow-raw-html pour passer directement les balises, ce que vous voulez lorsque votre Markdown se mêle délibérément en HTML - un <details> bloc, ou une image avec des attributs. Activez-le uniquement pour la source en laquelle vous avez confiance, car le code HTML brut d'un auteur non approuvé est un vecteur XSS.
Est-il sûr de coller une réduction sur le marché que je n'ai pas écrite ?
Oui. HTML est échappé par défaut, et l'aperçu en direct supprime également les balises de script et de style, les gestionnaires d'événements en ligne et JavaScript : URL avant le rendu. Rien de ce que vous collez n'est transmis n'importe où. Si vous créez un produit qui rend la démarque d'un inconnu, utilisez toujours un désinfectant dédié tel que Dompurify côté serveur, un filtre de prévisualisation n'est pas un substitut à un filtre.
Puis-je générer une table des matières à partir de mes en-têtes ?
Oui. Avec les ID de titre activés, chaque en-tête reçoit une ancre dédupliquée et l'outil crée une table des matières Markdown qui est liée à chacun. Copiez-le dans le haut de votre document et les liens résolvent contre les ID générés. Régénérez-le chaque fois que vos titres changent plutôt que de les maintenir à la main.
Ce convertisseur implémente-t-il entièrement CommonMark ?
Il implémente les constructions que les gens écrivent – en-têtes ATX et SETEX, paragraphes, emphase, liens, images, liens automatiques, blocs de quotes, listes imbriquées et lâches, code clôturé et en retrait, pauses thématiques, échappements backslash, ainsi que les extensions GFM. Les liens de style référence, les notes de bas de page et quelques rares cas de bord de blocs HTML de CommonMark ne sont pas couverts. Pour la conformité des bits exacts dans un pipeline de construction, utilisez Markdown-it, Remarque ou CMark.
Outils associés : Markdown en HTML · Entités HTML · minificateur HTML · compteur de mots · générateur de limace
Lecture connexe : La boîte à outils du développeur Web · Guide des outils de texte
