Le guide simplifié sur la syntaxe Markdown (avec exemples)
Ne cherchez plus la syntaxe pour formatter un document en Markdown, tout est là, dans ce guide simple et rapide à comprendre !
Article publié le 17/10/2023, dernière mise à jour le 17/10/2023
Un fichier Markdown est un simple fichier texte contenant une syntaxe facile et rapide à écrire pour rédiger du contenu “riche” avec des liens, des images, des citations, etc…
Ensuite, selon le logiciel utilisé, ce fichier est en général transformé et affiché comme une page web classique.
La syntaxe
Contrairement à d’autres langages de représentation de documents ou de données, en Markdown, les sauts à la ligne et les tabulations ont une signification, que vous allez découvrir tout au long de ce guide.
Les textes
Il est possible d’utiliser beaucoup de styles de texte différent, mais il y a quatre choses que vous ne pourrez pas modifier :
- la couleur
- l’alignement
- la police
- la taille
Titres
Comme en HTML, il existe 6 niveaux de titres, qui se composent comme ceci :
# Titre 1
## Titre 2
...
###### Titre 6
Attention, il faut toujours ajouter un espace entre “#” et le texte !
Paragraphes
Pour créer un nouveau paragraphe, il faut simplement laisser une ligne vide entre deux portions de texte :
Je suis un premier paragraphe
Je suis un deuxième paragraphe
Si vous revenez simplement à la ligne, votre texte sera ajouté à la suite du paragraphe en cours…
Liens
La syntaxe pour les liens est la suivante :
[Texte du lien](https://example.com)
Elle est très similaire à la syntaxe des images que nous verrons plus loin, attention à ne pas les confondre
Styles de texte
Pour faire ressortir des informations spécifiques, il suffit d’encadrer le texte désiré avec les caractères suivants :
_italique_
**gras**
**_gras/italique_**
~~barré~~
Attention à ne pas insérer d’espace (ex: ** gras **), sinon les styles ne seront pas détectés
Citations
Une citation doit être précédée du signe “>” :
> Je suis une citation
Certains interpréteurs permettent même d’encapsuler plusieurs citations en sautant une ligne et en ajoutant une tabulation.
Les listes
Liste non-ordonnée
Avec la possibilité de faire des “sous-listes”, en ajoutant une tabulation (ou 4 espaces) :
* Un élément
* Un autre élément
* Un élément enfant
* Un deuxième élément enfant
* Encore un
Toujours garder un espace entre le signe ”*” et le texte de l’élément !
Liste ordonnée
1. Un premier élément
2. Un deuxième élément
3. Un troisième élément
1. Un premier sous-élément
2. Un deuxième sous-élément
À noter qu’il n’est pas possible de noter les éléments des sous-listes “a.” ou même “1a.”, mais uniquement avec des chiffres comme la liste principale.
Images
Pour une image, en plus de l’URL, on peut indiquer un texte alternatif (sauf pour les images d’illustrations pure), et on peut également indiquer un titre :
Version simple :
![](https://example.com/image.jpg)
Version complète :
![Texte alternatif](https://example.com/image.jpg "Le titre de mon image")
Le titre n’apparaitra qu’au survol de l’image (sauf sur mobile)
Il est également possible de créer une image cliquable en entourant un bloc “image” par un bloc “lien”.
Tableaux
En créant un tableau avec les signes “|” et “-”, un tableau complet sera recréé en HTML :
| Janvier | Février | Mars | Avril |
|---------|---------|------|-------|
| 1200$ | 7000$ | 430$ | 120$ |
À noter que ce n’est pas l’alignement qui compte, mais cela reste plus facile à lire pour la personne qui édite le fichier !
Blocs de code
Il existe deux blocs de codes distincts, le premier qui est inséré dans du texte :
Je suis un exemple de code `console.log("Hello world")` inséré dans du texte.
Ou avec un bloc indépendant :
```js
const str = "Hello World"
console.log(str);
```
Le langage n’est pas obligatoire, mais cela pourra activer la coloration syntaxique si l’interpréteur le permet !
Un exemple de fichier Markdown
Voici un exemple de fichier basique pour une recette de cuisine, pour que vous puissiez voir les éléments réunis !
![Photos de crêpes](https://crepes.com/image.jpg)
# Recette de la pâte à crêpes
Tiré de la *fameuse recette* disponible sur [Internet](https://crepes.com/recette)
## Ingrédients
* Des œufs
* De la farine
* Du lait
* Du sucre
* ~~De l'huile de coude~~
> N'hésitez pas à faire **moitié-moitié** avec du sucre vanillé pour plus de goût !
### Tableau des quantités
| œufs | farine | lait | sucre |
|-------|--------|------|-------|
| 3 | 300g | 60cl | 20g |
## Étapes
1. Mettre la farine
2. Ajouter les œufs, le sucre, l'huile et le beurre
3. Mélanger délicatement
4. Faire cuire les crêpes une par une dans une poêle légère
## Partager
Pour intégrer cette recette sur votre site web, vous pouvez copier-coller le code suivante :
```html
<iframe href="https://crepes.com/recette?embed"></iframe>
```
Pour aller plus loin
Les commentaires
Les commentaires sont des éléments qui apparaissent dans votre fichier Markdown, mais pas dans le rendu final.
Il n’y a pas de solution officielle, mais l’une des syntaxes les plus compatible et la suivante :
(ligne vide)
[comment]: # (Mon commentaire)
Les éléments HTML
Par défaut, le markdown est censé être compatible la syntaxe HTML, par exemple, il est (théoriquement) possible de faire ça :
![Texte alternatif](https://example.com/image.jpg "Titre de l'image")
ou
<img src="https://example.com/image.jpg" alt="Texte alternatif" title="Titre de l'image"/>
Mais ça ne fonctionne pas toujours !
Certains interpréteurs ignorent volontairement les balises HTML, ou en ignore une partie spécifique (les iframe par exemple).
Les implémentations spécifiques
Certains logiciels/plateformes ajoutent des éléments à la syntaxe de Markdown de base, c’est par exemple le cas de GitHub, qui implémente un système de “case à cocher” sous forme de liste :
- [X] Add CriticMarkup support
- [ ] Add task list support
- [ ] Add Footnotes support
Si vous chercher les nombreuses implémentations et leurs différences, voilà une page qui résume tout ça
Aucun commentaire pour l'instant