ConnexionComment é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 :
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 BExemple 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 DExemple 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 6Exemple 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 ( ).
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 :
The post Comment écrire en Markdown ? Voici notre guide ! first appeared on IT-Connect.
