Comment écrire en Markdown ? Voici notre guide !

I. Présentation

Dans cet article, nous allons présenter la syntaxe de base pour écrire en Markdown, un langage de balisage léger (lightweight markup language) qui offre une syntaxe facile à lire, à écrire et à analyser ("parser") par d'autres programmes. Le Mardown est souvent utilisé pour la documentation technique et dans les systèmes de gestion de versions comme Git, notamment pour écrire les fichiers README.md qui décrivent le fonctionnement du code source d'un programme. La plupart des éditeurs de texte supportent le Markdown soit nativement ou via une extension.

Pour vous entraîner à écrire en Markdown (dont l'extension est .md), vous pouvez utiliser un environnement de développement léger comme Visual Studio Code (VS Code). Pour l'installer, référez-vous à l'article qui suit :

• Comment utiliser PowerShell avec Visual Studio Code ?

Lorsque vous aurez installé VS Code, ouvrez les Extensions (Ctrl+Shift+X) dans la barre latérale et installez l'extension "Markdown All in One".

Pour tester l'extension, créez un nouveau fichier "README.md" et appuyez sur l'icône "Open Preview to the Side" (Ctrl+K V).

Ce mode « preview » vous permettra de visualiser le rendu à mesure que vous écrirez.

Si vous ne souhaitez pas installer VS Code, vous pouvez rendre sur le site de Stackedit qui offre un éditeur de Markdown en ligne. Si vous disposez d'un compte sur une plateforme web d'hébergement de code source comme GitHub ou GitLab, il suffit de vous créer un nouveau fichier avec l'extension .md et vous verrez le rendu après avoir enregistré vos modifications.

Un fichier de référence pour la syntaxe du Markdown est disponible dans le dépôt GitHub d'IT-Connect, vous pouvez le cloner ou simplement le consulter à l'adresse suivante :

II. Syntaxe du Markdown

A. En-têtes

La première chose à maîtriser lorsque vous écrivez en Markdown sont les en-têtes, que l'on peut considérer comme des titres. Il existe deux manières de créer des en-têtes :

• Méthode 1 : Ajoutez un carré / croisillon / dièse (#) (hashtag) avant la chaîne caractères qui sera utilisée comme en-tête.

# En-tête niveau 1 
## En-tête niveau 2 
### En-tête niveau 3 
#### En-tête niveau 4

• Méthode 2 : Ajoutez un signe égal (=) en dessous de la chaîne caractères qui sera utilisée comme en-tête.

En-tête niveau 1=

En-tête niveau 2==

En-tête niveau 3===

En-tête niveau 4====

Exemple de rendu :

Vous verrez qu'il existe parfois deux manières d'utiliser la syntaxe du Markdown. Il est toujours préférable de choisir une seule méthode dans un même fichier.

Avec VS Code, vous verrez que l'éditeur vous proposera des alternatives et des suggestions si vous ne respectez pas la syntaxe.

B. Polices de caractères

Gras

Pour écrire en caractères gras, insérez un double tiret bas (underscore) (__chaîne __) au début et à la fin de la chaîne de caractères  (méthode recommandée).

Il est également possible d'utiliser deux astérisques (**) au lieu du tiret.

# Exemple 1
__ABC__ 
# Exemple 2
**ABC**

Italique

Pour écrire en italique, insérez un tiret bas (underscore) (_chaîne _) au début et à la fin de la chaîne de caractères (méthode recommandée).

Il est également possible d'utiliser un astérisque (*) au lieu du tiret.

# Exemple 1 
_ABC_
# Exemple 2 
*ABC*

Exemples de rendu :

C. Listes

Listes à puce

Pour créer des listes à puces, insérez un tiret (-) au début d'une ligne suivi d'un espace et poursuivez avec la chaîne de caractères.

Il est également possible d'utiliser un astérisque (*) au lieu du tiret.

- Élément A
- Élément B 
- Élément C
* Élément A 
* Élément B 
* Élément C
 - Sous-élément A 
 * Sous-élément B

Exemple de rendu :

Notez que VS Code souligne les puces indiquées (*) par une étoile parce que la méthode recommandée est celle du tiret (-).

Listes numérotées

Commencez une ligne avec le chiffre 0 ou 1 suivi d'un point (1.) et faire un retour de chariot pour que les lignes suivantes se numérotent automatiquement.

0. Élément A
1. Élément B
2. Élément C
3. Élément D

Exemple de rendu :

D. Blocs de citation

Blocs simples

Commencez la ligne avec un signe de comparaison "plus grand que" (>), ce qui va créer un bloc de citation indenté.

> Ceci est une citation en Markdown.

Blocs imbriqués

Vous pouvez créer un bloc de citation indenté et imbriqué à l'intérieur d'une citation. Commencez une ligne avec une indentation ("tab") et deux signes de comparaison "plus grand que" (>>).

> Ceci est une citation en Markdown. 
>> Ceci est une citation imbriquée en Markdown.

Exemple de rendu :

E. Blocs de code

L'une des fonctionnalités intéressantes du Markdown est qu'il permet d'afficher des blocs de code pour plusieurs langages de programmation avec la coloration syntaxique spécifique au langage.

Pour ajouter un bloc de code, insérez trois accents grave (backtick) au début de la ligne (ASCII : ALT + 96). Immédiatement après, spécifiez le langage de programmation utilisé (exemples : bash, pwsh, python) et terminez le bloc avec trois accents grave. Il suffit ensuite de placer vos lignes de code entre les deux blocs d'accents.

# Exemple en Bash

```bash ls -lah
mkdir test```
# Exemple en PowerShell

```pwshGet-ChildItem
```
# Exemple en Python

```pythonprint('Hello world')```

Exemple de rendu dans GitHub (qui est plus riche pour l'affichage du code source) :

F. Chaîne caractères surlignée

Insérer un accent grave ( `) avant et après la chaîne de caractères à surligner.

`Ceci permet de surligner une chaîne de caractères`

Exemple de rendu :

G. Tableaux

Le Markdown offre la possibilité de créer des tableaux :

• Commencez par définir des colonnes par des chaînes de caractères suivies d'une barre verticale (|).
• Faites un retour de chariot et ajoutez des tirets sous chaque nom de colonne suivis d'une barre verticale (|) pour définir les rangées (le nombre de tiret n'a pas d'importance).
• Pour chaque champ, entrez une chaîne caractère pour le contenu et la séparer avec une barre verticale (|) pour définir les colonnes.

I* l n'est pas nécessaire de fermer le dernier élément avec une barre verticale.

Colonne 1 | Colonne 2 | Colonne 3 
--------- | --------- |--------- 
Contenu 1 | Contenu 2 | Contenu 3 
Contenu 4 | Contenu 5 | Contenu 6

Exemple de rendu :

H. Table des matières

La fonctionnalité "table des matières" (TOC) est supporté par certaines plateformes web d'hébergement de code source comme Azure DevOps, mais elle n'est pas interprétée par tous les éditeurs (IDE). Parfois, vous trouverez un bouton pour faire afficher la table des matières (exemple : GitHub).

Pour l'utiliser, ajoutez "_TOC_" entre tirets bas à l'intérieur d'une paire de crochets ([[ ]]).

[[_TOC_]]

Exemple de rendu dans Azure DevOps qui supporte [[_TOC_]] :

I. Insérer des images

Images internes à un dépôt Git

Dans un dépôt Git, il est possible d'ajouter des fichiers d'images et d'y faire référence dans un document en Markdown pour les afficher.

Commencez la ligne avec un point d'exclamation (!) suivi d'une description entre crochets ([ ]), ajoutez l'image dans un répertoire de Git et précisez l'emplacement de l'image entre parenthèses ( ).

![Markdown Logo](./medias/markdown.logo.jpg)  
![Markdown Example](./medias/markdown.example.jpg)

Images externes du web

Il est également possible d'ajouter des images en provenance de sites web, mais il peut y avoir des contraintes sur le format et le positionnement sur la page. Le procédé est le même que pour une image interne.

Le site LightShot (https://app.prntscr.com/en/index.html) permet de faire des captures d'images et de les référencer directement en copiant le nouvel emplacement de l'image créée sur le site.

J. Insérer des liens

Liens externes (web)

Les liens externes (web) peuvent être insérés en ajoutant une description entre crochets ([ ]) suivie de l'URL du site web entre parenthèses ( ( ) ).

# Exemples 
- [Google Markdown Style Guide](https://google.github.io/styleguide/docguide/style.html) 
- [markdownguide.org](https://www.markdownguide.org/tools/) - [StackEdit Online Markdown Editor](https://stackedit.io/)

Liens internes

Dans Git, vous pouvez ajouter des liens vers d'autres pages du même dépôt de fichiers. Pour cela, il faut insérer une description entre crochets ([ ]) et ajouter l'emplacement du ficher entre parenthèses ( () ).

# Exemple [Document interne à lier](./Markdown/test.md)

Liens de références

Les liens de références (notes de bas de page) permettent d'insérer des liens numérotés (ou tout autre signe ou chaîne de caractères) pour ajouter une référence à une citation ou renvoyer à un contenu web ou interne.

Après la chaîne de caractères à référencer, ajoutez une suite de chiffres (des lettres ou un mot clé) entre crochets ([ ]) suivi d'un accent circonflexe (^).

Ajoutez la référence (lien vers une page web) après son numéro entre crochets ([ ]) suivi d'un deux points [:] à la fin du document. La référence sera cliquable par la suite.

# Insertion des liens de références 
[1^][2^][3^] 
[A^][B^]
[ref1^][ref2^] 
# Ajout des références au bas du fichier 
[1]:https://google.com 
[2]:https://microsoft.com 
[3]:https://linuxfoundation.org/

K. Caractère d'échappement

Utilisez la barre oblique inversée (backslash) comme caractère d'échappement avant un caractère réservé (-, *, > `) .

\*

L. Référer à des fichiers avec un lien relatif

Voici un tableau récapitulatif pour utiliser les liens relatifs pour référer à d'autres pages dans Git :

Principaux cas de figure	Lien relatif (Git)
Référer à un fichier sur la même branche dans le même répertoire	test.md
Référer à un fichier sur la même branche dans un sous-répertoire	./textes/test.md
Référer à un fichier sur la même branche dans un deuxième niveau de répertoires	../documents/textes/test.md
Référer à un fichier dans un répertoire sur une autre branche	/../documents/textes/test.md

M. Référer à une section d'un autre fichier

Ajoutez un carré / croisillon / dièse (#) immédiatement après le lien du fichier et ajouter le nom de la section.

 [lien](./test.md#Section1)

III. Conclusion

Dans ce tutoriel, nous avons passé en revue la syntaxe principale pour écrire en Markdown. Vous êtes maintenant outillés pour écrire des fichiers README.md et faire de la documentation dans vos dépôts Git.

Connaître le Markdown est une compétence essentielle aujourd'hui puisqu'il est utilisé dans toutes les plateformes collaboratives comme GitHub ou GitLab, mais aussi sur des sites de documentation. Il permet de respecter la pratique essentielle selon laquelle la documentation doit toujours être avec le code source d'un projet.

Le Markdown est très simple, mais, bien sûr, l'apprendre nécessite un peu de pratique. Donnez-vous comme discipline d'en faire à chaque fois que vous devez écrire de la documentation qui pourrait être réalisée en Markdown !

Pour aller plus loin, vous pouvez consulter les sites suivants :

• Markdown Guide
• Markdown Tutorial