Formatez votre Markdown avec notre outil Markdown. Prévisualisez et validez votre documentation.
La frustration du formatage
Vous rédigez de la documentation. Vous voulez une simple liste à puces. Vous passez 10 minutes à lutter contre le formatage d'un traitement de texte.
Vous voulez ajouter un exemple de code. La coloration syntaxique est fausse. La police est fausse. L'indentation est fausse.
Markdown résout cela. Vous écrivez en texte brut. De simples symboles contrôlent le formatage. Ça fonctionne.
Qu'est-ce que Markdown ?
Markdown est un langage de balisage léger. Vous écrivez en texte brut avec de simples symboles pour indiquer le formatage.
Il a été créé en 2004 par John Gruber. L'objectif était la lisibilité : un document Markdown doit pouvoir être publié tel quel, en texte brut, sans ressembler à du balisage.
Aujourd'hui, Markdown est partout. GitHub, Reddit, Stack Overflow, Notion et de nombreuses autres plateformes le prennent en charge.
Syntaxe Markdown de base
Voici les options de formatage les plus courantes :
Titres
# Titre H1 ## Titre H2 ### Titre H3
Emphase
*italique* ou _italique_ gras ou __gras__ *gras italique*
Listes
- Élément de liste 1 - Élément de liste 2 - Élément imbriqué 1. Élément numéroté 1 2. Élément numéroté 2
Code
Code en ligne `code` avec accents graves ```javascript // Bloc de code function hello() { console.log('Hello'); } ```
Structurer le document
Commencez par un titre H1 pour le titre du document, H2 pour les grandes sections et H3 pour les sous-sections. Ne sautez pas de niveau : passer de H2 à H4 casse la table des matières.
La plupart des moteurs génèrent une table des matières automatiquement à partir des titres. J'ai planifié un guide d'API de 4 000 mots à partir d'un plan comme celui-ci ; il m'a pris vingt minutes.
# Nom du projet## Installation### Depuis npm## Configuration### Variables d'environnement- Un titre H1 par document, réservé au titre
- Des niveaux cohérents : sections en H2, sous-sections en H3
- Des titres descriptifs pour que la table des matières soit explicite
Blocs de code avec indication de langage
Les blocs de code délimités commencent et se terminent par trois accents graves. Ajoutez le langage après l'ouverture, comme ```js ou ```bash ; la plupart des moteurs appliquent la coloration syntaxique automatiquement.
L'indication compte même sans coloration ; certaines plateformes l'utilisent pour le linting ou un bouton de copie. L'indentation est conservée à l'identique, gardez donc le source propre.
```jsconst crypto = require('crypto');const hash = crypto.createHash('sha256');hash.update('message');console.log(hash.digest('hex'));```- Fermer chaque bloc ; un délimiteur ouvert avale le reste du document
- Laisser une ligne vide avant les listes
- Placer la ligne de séparation directement sous l'en-tête
Tableaux, encadrés et images
Les tableaux viennent de GitHub Flavored Markdown : une ligne d'en-tête, une ligne de séparation de tirets et des lignes de données. Les deux-points règlent l'alignement à gauche, au centre ou à droite.
Les encadrés, les boîtes colorées de nombreuses documentations, ne font pas partie du Markdown standard. GitHub affiche `> [!NOTE]` et `> [!WARNING]`, mais vérifiez d'abord la plateforme cible.
Les images utilisent la syntaxe des liens précédée d'un point d'exclamation : . Utilisez un texte alternatif descriptif et des chemins relatifs pour que les images survivent à un clone.
> [!NOTE]> Cette fonctionnalité nécessite Node.js 18 ou plus récent.| Sortie | Octets || --- | ---: || sha256 | 32 || sha512 | 64 |Prévisualiser localement avant de publier
Les moteurs diffèrent sur de petits détails, regardez donc la sortie. Collez le document dans l'aperçu Markdown et vérifiez le résultat avant qu'il n'arrive dans un dépôt ou un CMS.
- Écrivez le document, un niveau de titre à la fois.
- Ouvrez l'aperçu Markdown et collez le source.
- Testez le même source sur la plateforme finale, car les moteurs diffèrent.
Pourquoi utiliser Markdown ?
Markdown présente plusieurs avantages par rapport aux traitements de texte traditionnels :
- Portable – Le texte brut fonctionne sur tous les appareils, pour toujours
- Favorable au contrôle de version – Git peut faire des diffs de fichiers Markdown facilement
- Rapide à écrire – Pas besoin de souris, gardez les mains sur le clavier
- Convertible en tout – HTML, PDF, DOCX, diapositives et plus
- Pérenne – Le texte brut ne devient jamais obsolète
- Sans distraction – Concentrez-vous sur le contenu, pas le formatage
Variantes de Markdown
Il existe de nombreuses variantes de Markdown, appelées « flavors ». Elles ajoutent des fonctionnalités à la spécification originale.
GitHub Flavored Markdown (GFM) ajoute les tableaux, listes de tâches et barrés. C'est la variante la plus populaire.
CommonMark est une version normalisée qui vise à résoudre les ambiguïtés de la spécification originale.
MultiMarkdown ajoute les notes de bas de page, citations et formules mathématiques. Populaire dans l'écriture académique.
FAQ
Q.Comment créer des tableaux ?
A.Utilisez des barres verticales et des tirets : | En-tête 1 | En-tête 2 | |-----------|-----------| | Cellule 1 | Cellule 2 | | Cellule 3 | Cellule 4 | La première ligne est l'en-tête, la deuxième exige un tiret par colonne.
Q.Comment ajouter des images ?
A.Utilisez cette syntaxe : 
Incluez toujours un texte alternatif descriptif. Pour les images du dépôt, utilisez un chemin relatif comme `../assets/diagramme.png`.
Q.Comment créer des liens ?
A.Utilisez cette syntaxe : Texte du lien Les liens de style référence gardent les URL longues hors de la prose : définissez l'URL une fois et écrivez `[CommonMark]` n'importe où.
Q.Comment ajouter une table des matières ?
A.La plupart des plateformes en génèrent une à partir des titres ; GitHub ajoute une table des matières aux README. Pour une table manuelle, des liens d'ancrage suffisent : `Installation` renvoie au titre avec ce slug.
Q.Comment créer des encadrés note et avertissement ?
A.Il n'existe pas de syntaxe Markdown standard pour les encadrés. GitHub affiche `> [!NOTE]` et `> [!WARNING]` dans les issues et les README ; sur un moteur CommonMark pur, les mêmes lignes apparaissent comme une citation.
Références
- Spécification CommonMark : https://spec.commonmark.org/
- Spécification GitHub Flavored Markdown : https://github.github.com/gfm/
- RFC 7764 – Guidance on Markdown : https://www.rfc-editor.org/info/rfc7764/
- MDN – Directives d'écriture Markdown : https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN
- Syntaxe Markdown d'origine (John Gruber) : https://daringfireball.net/projects/markdown/syntax
Prévisualisez le Markdown localement
Rendez et exportez le Markdown dans votre navigateur avec aperçu en direct et prise en charge GFM.
Conclusion
Markdown garde la documentation versionnable et révisable. Prévisualisez-la et exportez-la localement avec l'aperçu Markdown.
Commencez par une hiérarchie de titres propre et vérifiez le rendu avant de publier. Le format est petit ; contrôler la sortie garde la documentation honnête.