Le langage Markdown
Introduction
Markdown est un langage de balisage permettant de structurer et de mettre en forme un document via une syntaxe simple et lisible. Il est notamment utilisé pour rédiger des fichiers de documentation, des articles techniques, des fichiers README, des messages sur des plateformes collaboratives ou des prompts pour des modèles IA.
Contrairement à un traitement de texte traditionnel, le langage Markdown ne repose pas sur une interface graphique. La mise en forme du contenu d'un document est définie directement dans le texte, à l’aide de caractères tels que #, *, - ou encore `. Le document reste compréhensible, même lorsqu’il est consulté sans être converti en HTML.
Dans cet article, je vous propose de découvrir les principales syntaxes du langage Markdown, leur signification à l'aide d'exemples.
Les bonnes pratiques de rédaction
Pour conserver des documents Markdown lisibles et faciles à maintenir, voici quelques règles :
- Utiliser un seul titre de niveau 1 pour le titre principal du document.
- Respecter la hiérarchie des titres.
- Laisser une ligne vide autour des titres, des listes et des blocs de code.
- Préciser le langage utilisé dans chaque bloc de code.
- Utiliser des textes de liens explicites plutôt que « cliquez ici ».
- Fournir un texte alternatif pertinent pour chaque image.
- Privilégier les liens relatifs entre les pages d’une même documentation.
- Eviter d’utiliser du HTML lorsque la syntaxe Markdown suffit.
Il est également recommandé d’utiliser un outil de validation, ou linter, tel que Markdownlint. Celui-ci peut détecter les incohérences de structure et aider à appliquer des conventions communes à tous les documents.
Les limites du langage Markdown
Le langage Markdown est particulièrement adapté à la rédaction de contenus structurés, mais il ne couvre pas tous les besoins de mise en page. Par exemples, la fusion de lignes et de colonnes dans un tableau, les dimensions d’images, les couleurs, les polices, etc. nécessitent généralement des extensions, du HTML ou des feuilles de style CSS.
Aussi, toutes les plateformes n’implémentent pas exactement les mêmes fonctionnalités. Un document peut donc être rendu différemment selon qu’il est affiché sur GitHub, dans Visual Studio Code, avec MkDocs ou dans un autre outil. Pour produire une documentation portable, il est préférable de s’appuyer principalement sur la syntaxe de base.
Les fichiers Markdown
Les fichiers Markdown ont généralement l’extension .md. Un moteur de rendu transforme ensuite le contenu Markdown en HTML ou dans un autre format destiné à être affiché ou publié (epub, PDF, etc.).
Il existe plusieurs variantes de Markdown. La syntaxe de base est largement partagée, mais certaines fonctionnalités, telles que les tableaux, les listes de tâches, les notes de bas de page ou les blocs d’avertissement, dépendent du moteur de rendu ou des extensions activées.
Les paragraphes
Un paragraphe est constitué d’une ou de plusieurs lignes de texte. Pour créer un nouveau paragraphe, il faut laisser une ligne vide entre deux blocs de texte.
Syntaxe
Le langage Markdown permet de rédiger des documents structurés à l’aide d’une syntaxe simple.
Il est fréquemment utilisé pour écrire de la documentation technique.
Résultat
Le langage Markdown permet de rédiger des documents structurés à l’aide d’une syntaxe simple.
Il est fréquemment utilisé pour écrire de la documentation technique.
Les titres
Les titres permettent d’organiser un document de manière hiérarchique. Le langage Markdown propose six niveaux de titres. Ils sont définis en écrivant entre un et six caractères # au début de la ligne, suivis d’un espace.
Syntaxe
# Titre de niveau 1
## Titre de niveau 2
### Titre de niveau 3
#### Titre de niveau 4
##### Titre de niveau 5
###### Titre de niveau 6
Le titre de niveau 1 correspond au titre principal du document. Les autres niveaux servent à organiser ses sections et sous-sections.
La mise en valeur du texte
Le texte en italique
Pour afficher un texte en italique, il faut l’entourer d’un astérisque ou d’un tiret bas.
Résultat : Texte en italique
Le texte en gras
Pour afficher un texte en gras, il faut l’entourer de deux astérisques ou de deux tirets bas.
Résultat : Texte en gras
Le texte en gras et en italique
Trois astérisques permettent de combiner le gras et l’italique.
Résultat : Texte en gras et en italique
Le texte barré
Dans les moteurs compatibles avec cette extension, un texte peut être barré en l’entourant de deux tildes.
Résultat attendu : le texte « Texte supprimé » apparaît barré.
Cette syntaxe ne fait pas partie de la spécification Markdown originale, mais elle est notamment prise en charge par GitHub Flavored Markdown.
Les retours à la ligne
Pour créer un nouveau paragraphe, il suffit d'insérer une ligne vide.
Les listes non ordonnées
Une liste non ordonnée peut être créée à l’aide d’un tiret, d’un astérisque ou du signe +, suivi d’une espace.
Syntaxe
Résultat
- C#
- ASP.NET Core
- Entity Framework Core
Il est préférable de conserver le même marqueur dans l’ensemble d’une liste.
Les listes ordonnées
Une liste ordonnée est créée en faisant précéder chaque élément d’un nombre suivi d’un point.
Syntaxe
Résultat
- Installer le SDK .NET
- Créer le projet
- Compiler l’application
- Exécuter l’application
Il est possible d’utiliser 1. pour chaque élément. La plupart des moteurs calculent automatiquement la numérotation :
Cette forme facilite l’ajout, la suppression ou le déplacement d’un élément.
Les listes imbriquées
Une liste peut contenir des sous-listes. Les éléments enfants doivent être indentés, généralement avec quatre espaces.
Résultat :
- Développement
- C#
- F#
- Infrastructure
- Docker
- Kubernetes
Les listes de tâches
Certains moteurs de rendu, notamment GitHub, permettent de créer des listes de tâches. Une case vide est représentée par [ ] et une case cochée par [x].
- [x] Créer le projet
- [x] Ajouter les tests
- [ ] Rédiger la documentation
- [ ] Publier l’application
Selon la plateforme, ces cases peuvent être uniquement visuelles ou interactives.
Les citations
Une citation est créée en écrivant le caractère > au début d’une ligne.
Syntaxe
Résultat
Un code est lu beaucoup plus souvent qu’il n’est écrit.
Une citation peut contenir plusieurs paragraphes ou être imbriquée :
Code inclus dans du texte
Pour afficher un nom de classe, une fonction, une propriété ou une courte expression comme du code, il faut l’entourer d’accents graves. Si le texte à afficher contient lui-même un accent grave, il est possible de l’entourer de deux accents graves pour le déprécier.
Syntaxe
Résultat
L'instruction Console.WriteLine() permet d’écrire un message dans la console.
Les blocs de code
Un bloc de code est délimité par trois accents graves. Il est recommandé d’indiquer le langage après les accents graves d’ouverture, afin d’activer la coloration syntaxique lorsque le moteur l'affiche.
Exemple en C#
```csharp
public class Customer
{
public int Id { get; set; }
public required string Name { get; set; }
}
```
Résultat
Exemple en JSON
Exemple en ligne de commande
Les identifiants de langage couramment utilisés sont : csharp, json, yaml, xml, html, css, javascript, typescript, sql, bash et powershell.
Les liens hypertextes
Un lien hypertexte est composé du texte à afficher entre crochets, suivi de l’URL entre parenthèses.
Lien vers une page Web
Résultat : Site officiel de .NET
Lien avec une infobulle
Un titre facultatif peut être ajouté après l’adresse. Il apparaît au survol du lien.
Lien vers un autre fichier
Les liens relatifs permettent de relier les pages d’une même documentation.
Le chemin est généralement interprété à partir du fichier Markdown courant.
Lien vers une section
De nombreux moteurs génèrent automatiquement un identifiant à partir du texte d’un titre.
Les règles de génération de cet identifiant peuvent varier selon les outils, notamment pour les caractères accentuéss, les signes de ponctuation et les titres identiques.
Liens de référence
Les liens de référence sont utiles lorsqu’une même adresse est utilisée plusieurs fois, ou lorsque l’on souhaite alléger le texte.
Consultez la [documentation .NET][dotnet] et la [documentation C#][csharp].
[dotnet]: https://learn.microsoft.com/dotnet/
[csharp]: https://learn.microsoft.com/dotnet/csharp/
Les images
La syntaxe d’une image est proche de celle d’un lien, mais elle commence par un point d’exclamation :
Le texte placé entre crochets constitue le texte alternatif. Il décrit l’image lorsqu’elle ne peut pas être affichée et contribue à l’accessibilité du document. Une infobulle facultative peut également être précisée :
La syntaxe Markdown standard ne permet pas de définir directement les dimensions ou l’alignement d’une image. Cela dépend du moteur utilisé, de ses extensions, ou nécessite d'utiliser du CSS.
Les lignes de séparation
Une ligne horizontale peut être créée à l’aide d’au moins trois tirets, trois astérisques ou trois tirets bas.
Résultat :
Les tableaux
Les tableaux ne font pas partie de la syntaxe Markdown d’origine, mais ils sont pris en charge par de nombreux moteurs, dont GitHub Flavored Markdown et MkDocs avec l’extension appropriée.
Syntaxe
| Elément | Utilisation |
| --- | --- |
| C# | Langage de programmation |
| ASP.NET Core | Développement d’applications Web |
| EF Core | Accès aux données |
Résultat
| Elément | Utilisation |
|---|---|
| C# | Langage de programmation |
| ASP.NET Core | Développement d’applications Web |
| EF Core | Accès aux données |
La deuxième ligne sépare les en-têtes du contenu.
Alignement des colonnes
Les deux-points permettent d’indiquer l’alignement du contenu.
| Élément | Description | Quantité |
| :--- | :---: | ---: |
| Produit A | Centré | 10 |
| Produit B | Centré | 25 |
:---aligne le contenu à gauche.:---:centre le contenu.---:aligne le contenu à droite.
Les caractères spéciaux
Le langage Markdown utilise certains caractères pour définir la mise en forme. Pour les afficher littéralement, il est possible de les faire précéder d’une barre oblique inversée.
Cette technique est appelée échappement de caractères.
Les adresses Web et les adresses électroniques
De nombreux moteurs transforment automatiquement une adresse Web en lien. La syntaxe avec chevrons offre toutefois une forme explicite largement comprise :
Les notes de bas de page
Les notes de bas de page sont proposées par certains moteurs ou certaines extensions Markdown.
Markdown a été créé par John Gruber[^1].
[^1]: La première version de Markdown a été publiée en 2004.
La référence [^1] insérée dans le texte renvoie vers la définition correspondante. Cette fonctionnalité doit notamment être activée dans certaines configurations telles que MkDocs.
Les commentaires
Markdown ne définit pas de syntaxe standard pour les commentaires invisibles. Lorsque le moteur autorise le HTML, un commentaire HTML peut être utilisé :
Pour écrire un commentaire sur plusieurs lignes :
Les blocs d’avertissement et d’information
Les blocs d’information ne font pas partie du langage Markdown standard. Leur syntaxe varie selon l’outil utilisé.
Avec MkDocs Material et l’extension admonition, un bloc peut être écrit de la manière suivante :
Un bloc repliable peut être créé avec l’extension pymdownx.details :
Ces syntaxes doivent être activées dans le fichier de configuration de MkDocs avant de pouvoir être utilisées.
Un exemple de document complet
Le contenu ci-dessous combine plusieurs syntaxes présentées ci-dessus :
# Création d’une API avec ASP.NET Core
## Présentation
Dans cet article, nous allons créer une **API REST** avec *ASP.NET Core*.
> L’objectif est de mettre en place une première API simple et fonctionnelle.
## Prérequis
- Le SDK .NET
- Un éditeur de code
- Des connaissances de base en C#
## Création du projet
Exécutez la commande suivante :
```powershell
dotnet new webapi -n CatalogApi
```
Les principales étapes sont les suivantes :
1. Créer le projet
2. Ajouter les modèles
3. Développer les endpoints
4. Tester l’API
Pour plus d’informations, consultez la [documentation ASP.NET Core](https://learn.microsoft.com/aspnet/core/).