Tutoriel Markdown : Markdown

Le Markdown est une syntaxe incontournable pour tout développeur que l'on retrouve partout : dans les fichiers README.md sur GitHub, dans les commentaires d'issues, dans les outils de prise de note comme Obsidian ou Notion, et même dans les systèmes de commentaires de certains sites. Dans cet article on va voir ensemble ce qu'est le Markdown, sa syntaxe de base et ses extensions les plus utiles.

Création & Usage

Le Markdown a été créé par John Gruber et sa particularité réside dans le fait qu'il est lisible dans son format texte brut tout en étant convertissable en HTML (ou autre format plus avancé). C'est par exemple ce que fait GitHub lorsqu'il affiche le contenu d'un fichier README.md à la racine d'un projet : le markdown est converti en HTML pour offrir une présentation agréable.

L'avantage par rapport à des formats comme Word ou OpenOffice, c'est qu'on n'a pas besoin de logiciel particulier pour éditer un fichier Markdown. Un simple éditeur de texte suffit. Les éditeurs modernes comme Visual Studio Code offrent un support natif de cette syntaxe avec souvent aperçu en temps réel du rendu HTML.

Syntaxe de base

Pour créer son premier fichier, il suffit de créer un fichier avec l'extension .md (par exemple README.md). Ensuite, pour créer vos premier paragraphes il suffit d'écrire votre texte en séparant les paragraphes par une ligne de texte vide.

Titres

Pour créer un titre de premier niveau, on le préfixe d'un #. Pour un titre de second niveau on utilise ##, et ainsi de suite jusqu'à six niveaux.

# Titre de premier niveau

## Titre de second niveau

### Titre de troisième niveau

Il existe une syntaxe alternative avec des = ou des - sous le texte, mais la syntaxe avec les # est plus pratique et plus courante.

Emphase

Pour mettre en italique, on entoure le texte d'une * ou d'un _. Pour le mettre en gras, on utilise deux étoiles.

_texte en italique_
**texte en gras**

De cette manière, même sans interprétation, le document reste lisible et on identifie facilement ce qui est important.

Listes

Pour créer une liste non ordonnée, on préfixe chaque élément d'un tiret - (on peut aussi utiliser + ou *, mais par convention on utilise le tiret).

- Item 1
- Item 2
  - Sous-élément

Pour une liste ordonnée, on met le numéro suivi d'un point.

1. Premier point
2. Deuxième point

Citations

Pour citer un texte, on utilise le signe > en début de ligne.

> Cette citation peut
> s'étendre sur plusieurs lignes

Séparateur horizontal

Pour séparer visuellement des sections, on aligne trois tirets ou plus.

---

Code

Pour mettre en avant un mot-clé ou un nom de classe dans du texte, on l'entoure d'un backtick : `maClasse`.

Pour un bloc de code, on utilise trois backticks. On peut préciser le langage après les backticks d'ouverture pour activer la coloration syntaxique.

```php
<?php
echo "Hello World";

N'hésitez pas à toujours préciser le langage utilisé, ça aidera les interpréteurs Markdown à mieux convertir et mettre en couleur votre code.

### Liens

Pour créer un lien, on met le texte entre crochets suivi de l'URL entre parenthèses.

```markdown
[Grafikart](https://grafikart.fr)

Il existe aussi une approche par référence qui fonctionne comme les notes de bas de page sur Wikipédia. On met un identifiant entre crochets à la place de l'URL, et on définit la référence en bas du document.

On connaît un [super site][1]

[1]: https://grafikart.fr

Cette approche permet de garder le texte lisible tout en ayant tous les liens regroupés en bas du document.

Images

Pour les images, c'est la même syntaxe que les liens, mais préfixée d'un point d'exclamation.

![Texte alternatif](chemin/vers/image.png)

Syntaxe avancée

Le Markdown de base a été étendu par plusieurs acteurs, notamment GitHub avec le GitHub Flavored Markdown (GFM) qui ajoute des fonctionnalités supplémentaires.

Liens automatiques

Si on colle directement une URL dans le texte, elle sera automatiquement convertie en lien cliquable dans le rendu HTML.

Texte barré

Pour barrer du texte, on l'entoure de deux tildes.

~~texte barré~~

Tableaux

On peut créer des tableaux en utilisant des pipes | pour séparer les colonnes.

| Colonne 1 | Colonne 2 |
| --------- | --------- |
| Valeur 1  | Valeur 2  |

C'est une syntaxe un peu plus verbeuse, mais elle permet de créer des tableaux directement en texte brut. Des outils comme StackEdit offrent des raccourcis pour les créer plus facilement.

Listes de tâches

On peut créer des listes de tâches avec des cases à cocher.

- [ ] Tâche à faire
- [x] Tâche terminée

Sur des outils comme StackEdit ou GitHub, les cases sont interactives : on peut cocher directement une tâche et le Markdown source sera mis à jour.

Diagrammes avec Mermaid

Si le système qui interprète le Markdown le supporte (c'est le cas de GitHub et de StackEdit), on peut intégrer des diagrammes Mermaid. On utilise un bloc de code avec mermaid comme langage.

```mermaid
graph LR
    A --> B
    B --> C

Mermaid supporte plusieurs types de diagrammes : graphes, diagrammes de séquence, diagrammes de Gantt, etc. C'est un bon moyen de documenter visuellement le fonctionnement d'un système directement dans un fichier Markdown.

## Conclusion

Le Markdown est un format vraiment incontournable. Ce qui rend cette syntaxe si intéressante, c'est qu'elle est à la fois lisible telle quelle et convertible en HTML. On n'a pas besoin d'un logiciel complexe pour l'éditer ou le lire. Ce qui en fait un format idéal pour la prise de notre, l'écriture de documentation ou la description de problèmes.

Enfin, avec l'essor de l'IA, le Markdown prend encore plus d'importance. Les réponses des IA comme ChatGPT sont formatées en Markdown, et les agents de développement utilisent des fichiers Markdown (comme les fichiers `CLAUDE.md` ou `AGENTS.md`) pour comprendre le contexte d'un projet.