Blocks de code Markdown : Guide complet avec syntaxe, langages et exemples

Ici, je passe en revue les options de blocs de code dans Markdown — comment spécifier le langage de programmation, le formatage de différence et le nom de fichier du bloc de code.

Ce guide fait partie de notre Outils de documentation en 2026 : Markdown, LaTeX, PDF et workflows d’impression hub.

Aperçu des blocs de code Markdown

Les blocs de code Markdown affichent du code ou du texte préformaté dans les documents Markdown, en préservant la mise en forme et en permettant éventuellement la mise en surbrillance de la syntaxe. Il existe deux types principaux de mise en forme du code dans Markdown : le code inline et les blocs de code.

Types de blocs de code Markdown

Différences clés

• Le code inline utilise des backticks simples (`) et est utilisé pour de petits extraits de code au sein d’une phrase.
• Les blocs de code indentés utilisent quatre espaces ou une tabulation au début de chaque ligne. Ils ne prennent pas en charge la mise en surbrillance de la syntaxe et sont rares dans le Markdown moderne.
• Les blocs de code délimités utilisent des backticks triples (```) ou des tilde (~~~) avant et après le code. C’est la méthode préférée, surtout sur des plateformes comme GitHub, car :
  • Ils sont plus faciles à lire et à écrire.
  • Vous pouvez spécifier le langage de programmation immédiatement après les backticks ouvrants pour la mise en surbrillance de la syntaxe.
  • Ils préservent la mise en forme et prennent en charge le code multiligne.

Exemple d’un bloc de code délimité avec mise en surbrillance de la syntaxe :

Lorsque nous avons le texte au format Markdown suivant :

```python
def hello():
    print("Hello, world!")
```

La sortie rendue ressemble à :

def hello():
    print("Hello, world!")

Meilleures pratiques pour les blocs de code Markdown

• Utilisez des blocs de code délimités (trois backticks) pour le code multiligne afin d’assurer la clarté et la compatibilité sur les différentes plateformes.
• Spécifiez le langage après les backticks ouvrants pour la mise en surbrillance de la syntaxe (par exemple, ```python).
• Utilisez le code inline pour de courts extraits ou des commandes dans le texte.
• Évitez les blocs de code indentés sauf si nécessaire pour la compatibilité avec des versions antérieures, car ils ne prennent pas en charge la mise en surbrillance de la syntaxe et peuvent être moins lisibles.
• Placez une ligne vide avant et après les blocs de code délimités pour améliorer la lisibilité dans le Markdown brut.

Fonctionnalités spéciales

• Certaines plateformes prennent en charge d’autres identifiants de langage tels que diff pour afficher les changements de code, ce qui met en surbrillance les lignes ajoutées ou supprimées dans les revues de code.
• Pour afficher des backticks à l’intérieur d’un bloc de code, entourez le bloc d’un nombre plus élevé de backticks (par exemple, quatre backticks pour afficher trois backticks à l’intérieur).

Résumé rapide

Utilisez les blocs de code délimités avec un identifiant de langage pour la meilleure lisibilité et la mise en surbrillance de la syntaxe. Réservez le code inline aux extraits courts, et évitez les blocs indentés sauf si nécessaire pour la compatibilité.

Les blocs de code s’associent naturellement avec les tableaux dans Markdown pour construire une documentation technique bien structurée.

Mise en surbrillance de la syntaxe diff

La mise en surbrillance de la syntaxe diff vous permet d’afficher clairement les changements de code — utile dans la documentation, les revues de code et les blogs techniques.

• Utilisez des blocs de code délimités avec des backticks triples (```) pour commencer et terminer votre bloc.
• Spécifiez diff comme identifiant de langage immédiatement après les backticks ouvrants.

Exemple :

- ligne ancienne qui sera supprimée
+ nouvelle ligne qui sera ajoutée
  ligne non modifiée

• Les lignes commençant par - sont mises en surbrillance comme des suppressions (généralement en rouge).
• Les lignes commençant par + sont mises en surbrillance comme des ajouts (généralement en vert).
• Les lignes sans préfixe ne sont pas spécifiquement mises en surbrillance.

Bonnes pratiques :

• Placez une ligne vide avant et après votre bloc de code pour une meilleure lisibilité dans le Markdown brut.
• Notez que la mise en surbrillance diff ne colore que les lignes entières en fonction du caractère d’ouverture ; elle ne met pas en surbrillance les changements inline au sein d’une ligne.

Conseil : La mise en surbrillance diff est largement prise en charge sur GitHub, GitLab et la plupart des rendus Markdown, ce qui en fait un choix fiable pour communiquer les changements de code.

Langues prises en charge pour la mise en surbrillance de la syntaxe

L’ensemble exact des langues prises en charge dépend de le rendu ou la plateforme que vous utilisez. Markdown transmet l’identifiant de langage au moteur de rendu, qui applique la mise en surbrillance de la syntaxe appropriée. Cela importe lors de la conversion HTML en Markdown avec Python, car les balises <code> portant des attributs de classe de langage (par exemple, class="language-python") se cartographient directement à ces identifiants dans le bloc délimité.

Langues couramment prises en charge sur les principales plateformes (GitHub, VS Code, Bitbucket, Docusaurus, ReadMe) :

• Web & Scripting : javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
• Programmation : python (py), java, c, cpp (c++), csharp (c#), php, ruby, go, rust, scala, swift, kotlin, objective-c
• Données & Requêtes : sql, r, matlab
• Markup & Config : markdown, ini, toml, dockerfile, makefile
• Spécial : diff, mermaid, geojson, topojson, stl (pour les diagrammes et les visualisations de données sur GitHub)
• Autres : jsx, tsx, perl, lua, julia, dart, groovy, powershell, vb, elixir, erlang, fortran, haskell, lisp, scheme, et bien d’autres

Comment spécifier un langage :

```python
def hello():
    print("Hello, world!")
```

Identifiants de langage pris en charge par la plupart des rendus :

Note : La plupart des rendus sont insensibles à la casse pour les noms de langages. Si vous utilisez un identifiant non pris en charge, le bloc de code s’affiche en texte brut.

Pour trouver la liste complète des langues prises en charge :

• GitHub : Utilise Linguist, qui prend en charge des centaines de langages.
• VS Code & nombreux rendus web : Utilisent highlight.js ou Pygments — consultez leur documentation pour des listes exhaustives.
• Bitbucket : Se réfère à CodeMirror modes et aux lexers Pygments.

Spécifier un nom de fichier dans un bloc de code Markdown

Afficher le nom du fichier à côté d’un bloc de code aide les lecteurs à identifier à quel fichier appartient un extrait. Le support varie selon la plateforme.

1. Nom de fichier dans l’étiquette du bloc de code (syntaxe méta)

Certains moteurs Markdown (certains générateurs de site statique et plateformes de documentation) prennent en charge une syntaxe méta où vous ajoutez le nom du fichier après le langage, séparé par un deux-points :

```js:app.js
console.log("Hello, world!");
```

Cela affiche le nom du fichier au-dessus ou à côté du bloc de code. Ce site utilise le rendu Hugo, qui ne le prend pas en charge :

console.log("Hello, world!");

Note : Cela n’est pas pris en charge sur le Markdown de style GitHub.

2. Titre ou code inline avec le nom du fichier

Pour une compatibilité universelle (y compris GitHub, Stack Overflow et la plupart des rendus Markdown), placez le nom du fichier au-dessus du bloc de code en utilisant du code inline en gras :

**`app.js`**

```js
console.log("Hello, world!");
```

Ou avec un titre :

#### `app.js`

```js
console.log("Hello, world!");
```

Cela fonctionne partout et associe visuellement le nom du fichier au bloc de code.

3. Nom du fichier en tant que commentaire à l’intérieur du code

Incluez le nom du fichier en tant que commentaire à l’intérieur du bloc de code lui-même :

```js
// app.js
console.log("Hello, world!");
```

Cela est particulièrement utile lorsque vous souhaitez que le nom du fichier soit visible lors de la copie du code.

Résumé de la compatibilité

Utilisez du code inline en gras au-dessus du bloc de code pour une compatibilité maximale, et envisagez un commentaire à l’intérieur du code pour la clarté lors de la diffusion sur différentes plateformes.

Échapper les backticks à l’intérieur des blocs de code

Pour afficher des fentes de backticks à l’intérieur d’un bloc de code — par exemple lors de l’écriture de documentation sur Markdown lui-même — imbriquer le bloc dans un nombre plus élevé de backticks :

````markdown
```python
# Cette fente de backticks triple est à l'intérieur d'une fente de backticks quadruple
print("hello")
```
````

L’utilisation de quatre backticks comme fente externe permet d’afficher des exemples de fentes de backticks triples à l’intérieur, ce qui est pratique pour les tutoriels et les feuilles de triche Markdown.

Spécifique à Hugo : Le court-code highlight

Si vous utilisez Hugo, le court-code intégré highlight offre un contrôle plus important que les blocs délimités simples, y compris les numéros de lignes et les lignes mises en surbrillance :

{{< highlight python "linenos=true,hl_lines=2 4" >}}
def greet(name):
    print(f"Hello, {name}!")

greet("world")
{{< /highlight >}}

Options :

• linenos=true — afficher les numéros de lignes
• hl_lines=2 4 — mettre en surbrillance les lignes 2 et 4
• linenostart=10 — commencer le numérotage des lignes à partir de 10

Cela est particulièrement utile dans les tutoriels ou la documentation où vous souhaitez attirer l’attention sur des lignes spécifiques. Consultez la Feuille de triche Markdown pour plus de fonctionnalités de mise en forme, et la Feuille de triche Hugo pour une référence plus large sur les commandes et les modèles Hugo.

Liens utiles

• https://www.markdownguide.org/extended-syntax/
• https://docs.readme.com/rdmd/docs/code-blocks