Pourquoi convertir Markdown en HTML
Markdown est un langage de balisage léger adapté aux rédacteurs, mais le navigateur ne comprend que HTML. Le contenu écrit en Markdown doit être converti en HTML pour être affiché sur le web.
Scénarios courants :
- Publication d'articles de blog
- Rendu de sites de documentation
- Affichage de README
- Sortie HTML d'éditeurs enrichis
Correspondance syntaxique Markdown et HTML
Titres
Markdown :
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
HTML :
<h1>Titre de niveau 1</h1>
<h2>Titre de niveau 2</h2>
<h3>Titre de niveau 3</h3>
Paragraphe
Markdown : blocs de texte séparés par des lignes vides.
HTML : <p>Paragraphe</p>
Emphase
Markdown :
**gras**
*italique*
~~barré~~
HTML :
<strong>gras</strong>
<em>italique</em>
<del>barré</del>
Liens
Markdown :
[Texte du lien](https://example.com)
HTML :
<a href="https://example.com">Texte du lien</a>
Images
Markdown :
HTML :
<img src="image.png" alt="Texte alternatif">
Listes
Markdown liste non ordonnée :
- Élément 1
- Élément 2
HTML :
<ul>
<li>Élément 1</li>
<li>Élément 2</li>
</ul>
Markdown liste ordonnée :
1. Premier élément
2. Deuxième élément
HTML :
<ol>
<li>Premier élément</li>
<li>Deuxième élément</li>
</ol>
Code
Markdown code en ligne :
Ceci est du `code` en ligne
HTML : Ceci est du <code>code</code> en ligne
Markdown bloc de code :
Bloc de code
HTML :
<pre><code>Bloc de code</code></pre>
Avec coloration syntaxique :
const x = 1;
Après conversion, des marqueurs de coloration syntaxique sont inclus (nécessite une bibliothèque de coloration).
Citation
Markdown :
> Ceci est une citation
HTML :
<blockquote>Ceci est une citation</blockquote>
Ligne de séparation
Markdown :
---
HTML :
<hr>
Tableaux
Markdown :
| Nom | Âge |
| ---- | --- |
| Tom | 25 |
HTML :
<table>
<thead>
<tr><th>Nom</th><th>Âge</th></tr>
</thead>
<tbody>
<tr><td>Tom</td><td>25</td></tr>
</tbody>
</table>
Syntaxe étendue
Le Markdown standard (CommonMark) ne contient pas les fonctionnalités suivantes, mais la plupart des analyseurs les prennent en charge :
Listes de tâches
- [x] Terminé
- [ ] Non terminé
HTML :
<ul>
<li><input type="checkbox" checked disabled> Terminé</li>
<li><input type="checkbox" disabled> Non terminé</li>
</ul>
Notes de bas de page
Corps[^1]
[^1]: Contenu de la note
Barré
~~barré~~
Liens automatiques
Les URL sont automatiquement converties en liens (sans écrire manuellement ).
Listes de définitions, tables des matières, formules, etc.
Pris en charge par certains analyseurs, avec une compatibilité variable.
Points d'attention lors de la conversion
Perte de style
Markdown vers HTML génère uniquement des balises, sans styles. Le rendu dépend du CSS :
- Taille et espacement des titres
- Indentation et puces des listes
- Fond et police des blocs de code
- Bordures des tableaux
Il faut ajouter du CSS après la conversion pour un rendu agréable.
Sécurité XSS
Markdown autorise l'intégration de HTML. Lorsqu'un Markdown saisi par l'utilisateur est converti en HTML, les balises intégrées comme <script> sont conservées, ce qui peut provoquer des XSS.
Pratiques sûres :
- Utiliser du Markdown pur (désactiver le HTML intégré)
- Après la conversion en HTML, utiliser une bibliothèque de sanitize pour filtrer les balises dangereuses
- N'autoriser le Markdown que depuis des sources de confiance
Caractères d'échappement
Les caractères spéciaux dans Markdown (, #, _, ) doivent être échappés. Dans Markdown, écrivez \* pour afficher une astérisque ; après conversion en HTML, c'est ` et non une balise.
Chemin des images
Les images en chemin relatif dans Markdown conservent leur chemin après conversion en HTML. En cas de changement de répertoire, ajuster le chemin.
Liens d'ancrage
Les titres Markdown génèrent automatiquement des ancres (id). Les règles de génération varient selon les analyseurs, attention lors de la création de liens vers des ancres.
Outils de conversion
Conversion en ligne
Collez le Markdown, l'outil produit le HTML. Idéal pour une conversion unique.
Avec l'outil Markdown vers HTML :
- Coller le contenu Markdown
- L'outil analyse et convertit
- Sortie du code HTML
- Copier pour utiliser
Conversion côté navigateur, contenu non téléchargé.
Intégration dans les éditeurs
VS Code, Typora et d'autres éditeurs intègrent la prévisualisation Markdown vers HTML.
Conversion par programme
En JavaScript, utilisez les bibliothèques marked, markdown-it. En Python, les bibliothèques markdown, mistune.
Astuces de conversion
Unifier le style Markdown
Les différents dialectes Markdown (CommonMark, GFM, MDX) peuvent produire des résultats différents. L'équipe doit se mettre d'accord sur un dialecte.
Validation par prévisualisation
Après conversion, prévisualisez dans le navigateur et vérifiez :
- La hiérarchie des titres est correcte
- L'imbrication des listes est normale
- Les blocs de code sont colorés
- Les tableaux sont alignés
- Les images s'affichent
- Les liens sont cliquables
CSS associé
Préparez un CSS de rendu Markdown, appliquez-le au HTML converti pour un affichage soigné.
Conserver le Markdown original
HTML est le résultat du rendu, Markdown est le fichier source. Conservez le Markdown pour les éditions ultérieures, le HTML est régénéré à chaque fois.
Questions fréquentes
Le style est incorrect après conversion
Le HTML n'a pas de CSS. Ajoutez une feuille de style de rendu Markdown.
Les blocs de code ne sont pas colorés
Une bibliothèque de coloration syntaxique est nécessaire (comme highlight.js, Prism). Selon la configuration, l'outil de conversion peut intégrer la coloration.
Tableaux décalés
La syntaxe des tableaux Markdown n'est pas stricte (nombre de colonnes incohérent). Vérifier le format du tableau avant la conversion.
Affichage anormal des caractères spéciaux
Les caractères < > & ont une signification particulière en HTML. Ils doivent être échappés en < > &.
Résumé
Markdown vers HTML repose sur la correspondance syntaxique. Attention au CSS associé, à la sécurité XSS et à l'échappement des caractères spéciaux. L'outil Markdown vers HTML de DocsAll s'exécute côté navigateur, le contenu n'est pas transmis.