Comment utiliser l'éditeur Markdown
- Saisissez ou collez du Markdown dans l'éditeur à gauche.
- Regardez l'aperçu en direct se mettre à jour pendant que vous écrivez, rendu en Markdown GitHub (GFM).
- Cliquez sur Copier le HTML pour copier le HTML généré destiné à un site web, un CMS ou un e-mail.
- Ou copiez le Markdown lui-même pour un README, un ticket, une pull request ou une page de documentation.
Le rendu se fait dans votre navigateur, et votre texte n'est ni envoyé ni stocké. Le HTML produit est assaini : les scripts et les attributs dangereux présents dans le contenu collé sont supprimés avant l'affichage de l'aperçu.
Qu'est-ce que le Markdown ?
Markdown est un langage de balisage léger créé par John Gruber en 2004. Il utilise la ponctuation du texte brut pour la mise en forme : # pour les titres, * ou _ pour l'emphase, - pour les listes. Le texte source reste lisible tel quel, et un moteur de rendu le transforme en HTML.
La description d'origine laissait de nombreux cas limites indéfinis, et les implémentations n'étaient donc pas d'accord entre elles. CommonMark est une spécification détaillée qui lève ces ambiguïtés, et le Markdown GitHub est un sur-ensemble de CommonMark qui ajoute des fonctions que les développeurs utilisent tous les jours :
| Fonction GFM | Syntaxe |
|---|---|
| Tableaux | | Name | Value | avec une ligne de séparation |---|---| |
| Listes de tâches | - [ ] todo et - [x] done |
| Texte barré | ~~removed~~ |
| Liens automatiques | Les URL brutes comme https://example.com deviennent des liens |
| Blocs de code délimités | Trois accents graves, éventuellement suivis d'un nom de langage |
Aide-mémoire Markdown
# Heading 1
## Heading 2
**bold**, *italic*, `inline code`
- Bullet item
- Nested item (indent two spaces)
1. Numbered item
[Link text](https://example.com)
> A blockquote
```python
print("fenced code with a language")
```Problèmes courants en Markdown et comment les corriger
Un titre qui ne s'affiche pas. CommonMark exige une espace après les dièses. #Title est du texte brut ; # Title est un titre.
Des lignes fusionnées en un seul paragraphe. Un simple saut de ligne à l'intérieur d'un paragraphe est traité comme une espace. Laissez une ligne vide pour commencer un nouveau paragraphe, ou terminez une ligne par deux espaces ou une barre oblique inverse pour obtenir un saut de ligne forcé. (Les commentaires GitHub traitent les simples sauts de ligne autrement que les fichiers README, ce qui est une source fréquente de confusion.)
Une liste ou un bloc de code qui s'interrompt trop tôt. Le contenu qui appartient à un élément de liste doit être indenté de façon à s'aligner sur le texte de l'élément. Pour du code dans une liste, indentez tout le bloc délimité :
1. Install the package:
```bash
npm install example
```
2. Run it.Un tableau qui ne s'affiche pas. Un tableau GFM a besoin d'une ligne d'en-tête, d'une ligne de séparation avec au moins trois tirets par colonne et, en général, d'une ligne vide avant lui. Utilisez des deux-points dans la séparation (:---, :---:, ---:) pour aligner les colonnes.
Une mise en forme involontaire. Des caractères comme *, _ et # peuvent déclencher une mise en forme. Échappez-les avec une barre oblique inverse, par exemple \*not italic\*, ou placez-les entre accents graves.
Conseils et bonnes pratiques
- Ajoutez toujours un langage après les accents graves d'ouverture pour que les blocs de code aient une coloration syntaxique là où elle est prise en charge.
- Rédigez un texte alternatif pertinent pour les images ; il est lu par les lecteurs d'écran et affiché si l'image ne se charge pas.
- Écrivez une phrase par ligne dans les longs documents ; Markdown les regroupe en paragraphes, et les différences entre versions deviennent beaucoup plus propres.
- Collez d'abord vos exemples JSON ou YAML dans le Formateur et validateur JSON ou le Formateur et validateur YAML, pour que les blocs de code de votre documentation soient valides et propres.
- Si vous collez le HTML généré dans une page web, passez-le dans le Formateur HTML pour l'indenter proprement.
Questions fréquentes
Quelle différence y a-t-il entre Markdown et le Markdown GitHub ?
GFM est un sur-ensemble du Markdown CommonMark défini par GitHub. Il ajoute les tableaux, les listes de tâches, le texte barré, des liens automatiques étendus et quelques restrictions sur le HTML brut. La plupart des README écrits pour GitHub s'affichent ici de la même façon.
Puis-je utiliser du HTML dans du Markdown ?
Oui, Markdown autorise le HTML en ligne. Par sécurité, l'aperçu assainit le résultat : des balises comme <script>, des attributs de gestionnaire d'événement tels que onclick et des liens javascript: sont donc supprimés.
Pourquoi mon Markdown s'affiche-t-il différemment sur un autre site ?
Les plateformes utilisent des variantes de Markdown différentes et leurs propres feuilles de style. La syntaxe de base (titres, emphase, listes, liens, code) est cohérente, mais les tableaux, les sauts de ligne et les extensions comme les notes de bas de page ou les formules mathématiques varient d'un moteur de rendu à l'autre.
Comment convertir du Markdown en HTML ?
Écrivez ou collez votre Markdown, vérifiez l'aperçu, puis cliquez sur Copier le HTML. Le résultat est du HTML sémantique simple (titres, paragraphes, listes, tableaux) sans mise en forme : il reprend donc le CSS de la page dans laquelle vous le collez.
Mis à jour