Le guide simplifié sur la syntaxe Markdown (avec exemples)

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