Aller au contenu principal
Hemen Dönüştür
Choose language: fr

Formats de fichiers

Qu'est-ce que le Markdown ? Syntaxe, CommonMark et GFM

Le Markdown est un langage de balisage léger qui ajoute titres, listes et liens à du texte brut avec quelques symboles. Nous présentons son histoire, ses normes et ce qui survit quand on transforme des fichiers MD en Word ou en PDF.

Auteur: Hemen Dönüştür Editör EkibiPublié le: 9 min de lecture

Badge de fichier marqué MD avec un symbole dièse

Pensez au README d'un projet logiciel, aux listes à titres d'une application de prise de notes ou aux mots que vous mettez en gras avec des astérisques dans une messagerie. Derrière tout cela se cache la même idée : le Markdown. Le Markdown est un langage de balisage léger qui permet de définir des titres, des listes, des liens et des tableaux en ajoutant quelques symboles simples à du texte brut. Le fichier reste lisible dans n'importe quel éditeur de texte, mais il peut être transformé à tout moment en page HTML soignée, en document Word ou en PDF. Cet article retrace la naissance du Markdown, sa syntaxe de base, les différences entre CommonMark et GitHub Flavored Markdown, et ce qu'il faut surveiller lors de la conversion de fichiers MD.

Qu'est-ce que le Markdown ?

Le Markdown désigne à la fois un ensemble de conventions d'écriture et, couramment, les outils qui convertissent en HTML un texte écrit selon ces conventions. Les fichiers sont généralement enregistrés avec l'extension .md ou .markdown. Selon son créateur, John Gruber, l'objectif principal de sa conception est la lisibilité : un document Markdown doit pouvoir être publié tel quel, en texte brut, sans avoir l'air d'être truffé de balises ou d'instructions de mise en forme. Là où le HTML demande <strong>important</strong>, le Markdown utilise **important**, et même la version brute se lit naturellement.

Un peu d'histoire

John Gruber a créé le Markdown en 2004, avec Aaron Swartz comme interlocuteur pour éprouver ses idées. La syntaxe s'inspire des conventions des e-mails en texte brut (astérisques pour la mise en valeur, tirets pour les listes) et de langages de balisage antérieurs comme setext et Textile. La version 1.0.1 de Markdown.pl, le script Perl que Gruber a publié sur son site Daring Fireball, est datée du 17 décembre 2004.

La description de Gruber était cependant une explication par l'exemple plutôt qu'une spécification formelle. Les cas ambigus (listes imbriquées, blocs de code indentés, mélange avec du HTML) ont conduit chaque implémentation à faire ses propres choix, et un même texte a commencé à produire des résultats différents selon les outils. Deux grandes réponses ont suivi :

  • CommonMark (2014) : une spécification menée par John MacFarlane, qui définit le Markdown sans ambiguïté et le rend testable grâce à des centaines d'exemples. Les premières versions sont parues à l'automne 2014 ; la version actuelle est la 0.31.2, datée du 28 janvier 2024. La spécification n'a pas encore été déclarée en version 1.0.
  • GitHub Flavored Markdown (GFM, 2017) : la spécification formelle de GitHub, construite sur CommonMark. Elle ajoute des extensions comme les tableaux, les listes de tâches, le texte barré, les liens automatiques étendus et, par sécurité, le filtrage de certaines balises HTML brutes. La dernière spécification publiée est la 0.29-gfm, datée du 6 avril 2019.

Le Markdown a aussi trouvé sa place dans l'infrastructure d'Internet : la RFC 7763, publiée en mars 2016, a enregistré le type de média (type MIME) text/markdown, avec un paramètre facultatif variant qui indique la variante de Markdown voulue par l'auteur.

Les principales variantes du Markdown

Au-delà de CommonMark et de GFM, d'autres variantes sont répandues. La RFC 7764, publiée en même temps que la RFC 7763, en a enregistré plusieurs et a donné des recommandations d'usage :

  • Markdown Extra : une extension précoce qui a ajouté les notes de bas de page, les listes de définitions et les tableaux.
  • MultiMarkdown : une variante destinée à l'écriture universitaire, avec métadonnées, citations et renvois.
  • Pandoc Markdown : la variante utilisée par le convertisseur Pandoc, avec de nombreuses extensions pour écrire des livres et des articles.

Une règle pratique : si votre document n'utilise que des titres, des listes, des liens, du code et des tableaux simples, il s'affichera de la même façon presque partout. Si vous comptez sur les notes de bas de page, les listes de définitions ou des types de blocs particuliers, vérifiez quelle variante l'environnement cible prend en charge.

La syntaxe de base

La partie du Markdown dont vous avez besoin au quotidien s'apprend en quelques minutes :

# Titre de niveau un
## Titre de niveau deux
Ce paragraphe contient du **gras**, de l'*italique* et du `code`.
- Liste à puces
- Deuxième élément
  - Sous-élément indenté
1. Liste numérotée
2. Deuxième étape
[Texte du lien](https://example.com)
![Description de l'image](image.png)
> Citation
```
Bloc de code sur plusieurs lignes
```

Les tableaux et les listes de tâches, ajoutés par GFM, se présentent ainsi :

| Format | Extension |
|--------|-----------|
| Markdown | .md |
| Texte brut | .txt |
- [x] Rédiger le brouillon
- [ ] Le relire

Les paragraphes sont séparés par des lignes vides. Un simple retour à la ligne est considéré comme faisant partie du même paragraphe dans la plupart des implémentations ; pour forcer un saut de ligne, terminez la ligne par deux espaces. Vous pouvez aussi écrire du HTML directement dans le Markdown. CommonMark l'autorise, même si des environnements comme GFM bloquent certaines balises par sécurité.

Où utilise-t-on le Markdown ?

  • Développement logiciel : README, journaux des modifications et guides de contribution, ainsi que les tickets et les commentaires de revue de code sur des plateformes comme GitHub et GitLab.
  • Documentation technique : générateurs de sites statiques qui construisent des sites web à partir de fichiers Markdown.
  • Prise de notes : de nombreuses applications de notes stockent ou exportent les notes en Markdown.
  • Plateformes de discussion et communautés : des plateformes comme Reddit et Discord utilisent des variantes du Markdown.
  • Écriture et édition : production de HTML, de PDF, de DOCX et d'EPUB à partir d'une seule source Markdown avec des outils comme Pandoc.
  • Outils d'IA : les assistants d'IA conversationnels mettent souvent leurs réponses en forme en Markdown.

Points forts et points faibles

Points fortsPoints faibles
Lisible même à l'état brutLes variantes ne se comportent pas de la même façon
Texte brut : léger, portable, adapté à la gestion de versionsNi polices, ni couleurs, ni mise en page
Se convertit facilement en HTML, PDF et WordPas de tableaux complexes (cellules fusionnées)
S'apprend en quelques minutesLes images sont dans des fichiers séparés
Lié à aucun programmeLes erreurs d'espaces et d'indentation modifient le résultat

Quels programmes ouvrent le Markdown ?

Comme le Markdown est du texte brut, il s'ouvre dans n'importe quel éditeur de texte, Bloc-notes et TextEdit compris. Pour un aperçu mis en forme, vous pouvez utiliser l'aperçu Markdown intégré à Visual Studio Code ou des éditeurs dédiés comme Obsidian et Typora. GitHub et GitLab affichent automatiquement les fichiers .md des dépôts. Word, en revanche, n'ouvre pas le Markdown comme du texte mis en forme : il faut d'abord convertir le fichier.

Problèmes courants et solutions

Une liste ou un titre ne s'affiche pas

CommonMark exige une espace après le marqueur de titre : ## Titre, et non ##Titre. Une liste qui suit un paragraphe a aussi souvent besoin d'une ligne vide intermédiaire pour s'afficher correctement.

Les lignes se collent les unes aux autres

Un simple retour à la ligne ne crée pas de nouveau paragraphe. Laissez une ligne vide pour un nouveau paragraphe, ou terminez la ligne par deux espaces pour un saut de ligne au sein d'un paragraphe.

Un tableau fonctionne sur une plateforme mais pas sur une autre

Les tableaux ne font partie ni du Markdown original de Gruber ni du noyau de CommonMark ; ils proviennent d'extensions comme GFM. Vérifiez quelle variante la plateforme cible prend en charge.

Un paragraphe qui commence par un nombre devient une liste numérotée

Une ligne comme « 2024. a été une année chargée » commence par des chiffres suivis d'un point : elle peut donc être interprétée comme une liste. Échappez le point avec une barre oblique inverse (2024\.) pour l'éviter.

Conseils pour convertir des fichiers Markdown

Sur notre convertisseur, les fichiers Markdown sont envoyés sur notre serveur et supprimés dans les 30 minutes. Pour la lecture, nous utilisons la bibliothèque Markdig avec CommonMark et des extensions de style GitHub (tableaux, listes de tâches, notes de bas de page, liens automatiques).

  • Markdown en PDF et Markdown en Word conservent les titres, les listes, les blocs de code, les citations et les tableaux avec bordures. Les cases à cocher des listes de tâches sont transformées en caractères ☑ et ☐ pour rester visibles dans Word et en PDF. Le texte est composé par défaut dans une police à empattements de 12 pt, et les blocs de code dans une police à chasse fixe.
  • Markdown en HTML transforme un README en page web autonome, avec son encodage déclaré.
  • Dans l'autre sens, Word en Markdown, HTML en Markdown et PDF en Markdown produisent du Markdown compatible GitHub : titres, gras et italique, listes, tableaux, liens, blocs de code et citations sont conservés ; les polices, les couleurs et la mise en page disparaissent. Dans les tableaux sans ligne d'en-tête, la première ligne devient l'en-tête, car les tableaux GFM en exigent une. Les paragraphes ordinaires qui commencent par un nombre, comme « 1. Clause », sont échappés pour ne pas devenir accidentellement des listes. Le fichier est enregistré en UTF-8 sans BOM.

Questions fréquentes

Comment ouvrir un fichier MD ?

N'importe quel éditeur de texte l'ouvre. Pour le voir mis en forme, utilisez l'aperçu de Visual Studio Code ou un éditeur Markdown ; si vous voulez le lire dans Word, convertissez-le en DOCX.

Quelle différence entre CommonMark et GitHub Flavored Markdown ?

CommonMark définit la syntaxe de base du Markdown avec des règles précises. GFM est un sur-ensemble qui ajoute des extensions à CommonMark, comme les tableaux, les listes de tâches, le texte barré et les liens automatiques étendus.

Peut-on faire des tableaux en Markdown ?

Oui : avec des extensions comme GFM, vous pouvez écrire des tableaux simples à l'aide de barres verticales et de tirets. Pour des structures complexes comme les cellules fusionnées, utilisez un tableau HTML ou préparez le document dans Word.

Quelle différence entre Markdown et HTML ?

Le Markdown est un format d'écriture plus simple, conçu pour être converti en HTML. Il ne peut pas exprimer tout ce que permet le HTML, mais sa forme brute est bien plus lisible. Vous pouvez toujours écrire du HTML dans du Markdown en cas de besoin.

Le Markdown a-t-il une norme officielle ?

La description originale de Gruber n'est pas une spécification formelle. La définition précise la plus largement acceptée aujourd'hui est CommonMark, et le type de média text/markdown a été enregistré par la RFC 7763 en mars 2016.

Sources

Convertisseurs associés

Articles associés

Tous les articles