La comparaison en bref
Choisissez Markdown lorsque la vitesse d'écriture, la lisibilité de la source, la portabilité et les diff de contrôle de version comptent le plus. Choisissez HTML lorsque le document a besoin de sémantique ou de composants que Markdown ne peut pas exprimer, ou lorsque vous possédez directement la page web rendue.
| Critère | Markdown | HTML |
|---|---|---|
| Lisibilité de la source | Élevée pour les documents courants | Plus de balises autour du contenu |
| Contrôle de la présentation | Délégué au moteur de rendu | Contrôle précis avec CSS |
| Vocabulaire documentaire | Réduit et normé | Large ensemble d'éléments sémantiques |
| Portabilité | Forte dans la syntaxe courante | Forte sur le web |
| Interactivité | Généralement aucune | Possible avec des scripts et composants |
| Surface de sécurité | Dépend du moteur de rendu | Le contenu actif exige des contrôles stricts |
Là où Markdown est plus fort
Markdown maintient l'auteur concentré sur la hiérarchie et les mots du document. Un titre est un titre, sans décision sur les noms de classes, les espacements ou les points de rupture responsifs. Cela accélère l'écriture technique courante et apaise les diff de relecture.
La contrepartie est que le moteur de rendu a le dernier mot. Le même tableau ou la même liste de tâches peut rendre différemment sur GitHub, dans un éditeur ou un générateur de site statique, et certaines extensions peuvent ne pas exister partout.
Là où HTML est plus fort
HTML peut représenter la navigation, les figures, les panneaux de détails, les formulaires, les définitions, les médias et des relations d'accessibilité riches que le Markdown de base ne peut pas. Combiné avec CSS, il prend en charge des mises en page précises et des systèmes de design.
Cette puissance ajoute des responsabilités. Les auteurs ou les systèmes de composants doivent produire une sémantique valide, une interaction adaptée au clavier, une mise en forme responsive et une frontière de contenu sûre. Le HTML brut d'un document non fiable ne doit jamais être injecté sans assainissement.
La plupart des systèmes de documentation utilisent les deux
Un pipeline courant stocke les articles en Markdown, les convertit en HTML, puis applique des composants et du CSS partagés. Les auteurs disposent d'une source lisible tandis que le site web obtient navigation, coloration syntaxique, mise en page responsive et fonctionnalités d'accessibilité.
Certains systèmes autorisent le HTML brut dans Markdown. Utilisez cette porte de sortie avec parcimonie : elle réduit la portabilité et peut élargir la surface de sécurité. Privilégiez un composant ou une extension documenté lorsque la plateforme de publication en propose un.
Markdown: ## API reference [Read the schema](/schema) HTML: <h2>API reference</h2> <a href="/schema">Read the schema</a>
La conversion de HTML en Markdown est volontairement avec pertes
Les titres sémantiques, les paragraphes, les liens, les listes, le code et les tableaux simples ont généralement des équivalents clairs. La mise en page CSS, les noms de classes, les scripts, les formulaires et les widgets personnalisés n'en ont pas. Une bonne conversion conserve le document lisible et laisse l'application web de côté.
Après la conversion, inspectez les liens relatifs, les références d'images, les blocs de code et tous fragments bruts. L'aperçu de l'éditeur doit assainir la sortie non fiable, mais la publication mérite toujours sa propre politique de contenu.