J'ai écrit Markdown tous les jours ouvrables depuis des années - plugin READMEs, changelogs, docs for 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 : Le Markdown est un format d'écriture ; 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 rejoignent en un seul paragraphe à moins que vous ne terminiez une ligne avec deux espaces (ou n'allumez une option " ; breaks" ;), le HTML brut est soit passé ou échappé en fonction de l'analyseur' ; s paramètres de confiance, et le dialecte GitHub' ; s (GFM) ajoute des tables, des listes de tâches, un strikethrough et un bare-URL en liaison automatique par-dessus du marque courante ligne de base. Le code clôturé se compile pour
<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'avoir été balisé avec des balises C'est pourquoi la syntaxe emprunte aux conventions que les gens utilisaient déjà dans le courrier électronique - des astérisques autour d'un mot pour mettre l'accent, une ligne de tirets sous un titre, 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 de documents, une application de chat - a d'abord exécuté un analyseur et a mis 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, testable 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, accentuation, liens, images, listes, blockquotes, blocs de code, pauses 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 restitue. Ce n'est pas un bug ; c'est la spécification, et elle existe pour que vous puissiez envelopper votre prose sur 80 colonnes dans un éditeur de texte sans que cet emballage ne fuie 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 à la fin d'une ligne produire 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 HTML en ligne - la spécification originale indique explicitement que tout HTML que vous écrivez passe directement. C'est une fonctionnalité lorsque vous en êtes l'auteur (vous voulez 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 biographie de profil utilisateur, un wiki public - partout où des inconnus écrivent un Markdown que d'autres personnes lisent - doit soit échapper au HTML, soit assainir la sortie avec un véritable désinfectant (DOMPurify est la réponse habituelle, et c'est un véritable désinfectant précisément parce que un regex ne suffit pas 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 restitue - une mesure de profondeur de défense, donc coller quelqu'un d'autre' ; Le README dans le volet d'aperçu ne peut pas exécuter son code. Il s'agit d'une mesure de sécurité d'aperçu, pas d'un désinfectant à usage général : si vous créez un produit qui rend l'utilisateur Markdown, utilisez un serveur de désinfectant dédié 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 devrait 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 README, un journal des modifications, des notes de version, un brouillon. Mises à jour de sortie au fur et à mesure 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 d'aperçu et confirmez la structure La ligne de statistiques vous indique les mots, les titres, les liens, les images, les blocs de code et le temps de lecture - pratique pour vérifier un message est la longueur que vous pensiez qu'elle était avant de le 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 déposez ou copiez la table des matières générée - une liste imbriquée Markdown renvoyant à chaque ancre de titre, 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
Beaucoup de champs CMS, de plateformes de messagerie et de panneaux d'administration existants prennent du HTML et rien d'autre Si vous rédigez dans Markdown - et la plupart des gens qui écrivent régulièrement le font - c'est le pont avec lequel Convertir 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 un contributeur' ; s Markdown, regardez le HTML émis, et vous pouvez voir immédiatement s'ils ont utilisé de vrais titres ou mis une ligne en gras pour en simuler un - une habitude qui détruit la structure et l'accessibilité des documents Les lecteurs d'écran naviguent par titre ; **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 Markdown qui extrait une dépendance de 200 Ko dans une page dont tout le but est d'être rapide est une mauvaise transaction.
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 Markdown dans l'éditeur et le HTML apparaît immédiatement - il n'y a pas de bouton de conversion et pas de fichier à télécharger Activez GitHub Flavored Markdown si votre source utilise des tables ou des listes de tâches, puis copiez le HTML ou téléchargez-le sous forme de fichier.html. Tout s'exécute 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 sauts de ligne - c'est le comportement utilisé par les commentaires GitHub et la plupart des applications de chat, mais ce n'est pas ce que font les fichiers README.
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 un texte littéral plutôt que comme une balise Activez l'option autoriser-brut-HTML pour faire passer les balises directement, ce que vous voulez lorsque votre Markdown se mélange délibérément en HTML - a <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 en outre les balises de script et de style, les gestionnaires d'événements en ligne et les URL javascript : avant le rendu Rien de ce que vous collez n'est transmis nulle part Si vous créez un produit qui rend Markdown à partir d'étrangers, utilisez toujours un désinfectant dédié tel que DOMPurify côté serveur - un filtre d'aperçu n'en remplace pas un.
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 réellement - vedettes ATX et setext, paragraphes, accentuation, liens, images, liens automatiques, blockquotes, listes imbriquées et libres, code clôturé et en retrait, pauses thématiques, évasions de barre oblique inverse - 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 bloc HTML CommonMark ne sont pas couverts. Pour la conformité exacte des bits 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
