Blocs de code Markdown : guide complet avec syntaxe, langages et exemples

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

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

Vue d’ensemble des blocs de code Markdown

Les blocs de code Markdown affichent du code ou du texte préformaté au sein des documents Markdown, préservant la mise en forme et activant éventuellement la coloration syntaxique. Il existe deux types principaux de formatage de code en 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 destiné à du code court 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 coloration syntaxique et sont rares dans le Markdown moderne.
• Les blocs de code clôturés (fenced blocks) utilisent des triples backticks (```) ou des tildes (~~~) avant et après le code. C’est la méthode préférée, notamment sur des plateformes comme GitHub, car :
  • Ils sont plus faciles à lire et à écrire.
  • Vous pouvez spécifier le langage de programmation juste après les backticks ouvrants pour activer la coloration syntaxique.
  • Ils préservent la mise en forme et prennent en charge le code multiligne.

Exemple d’un bloc de code clôturé avec coloration syntaxique :

Lorsque nous avons le texte formaté Markdown suivant :

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

Le rendu affiché ressemble à ceci :

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

Bonnes pratiques pour les blocs de code Markdown

• Utilisez des blocs de code clôturés (triples backticks) pour le code multiligne afin d’assurer clarté et compatibilité entre les plateformes.
• Spécifiez le langage après les backticks ouvrants pour la coloration syntaxique (par ex. ```python).
• Utilisez le code inline pour de petits extraits ou commandes au sein du texte.
• Évitez les blocs de code indentés sauf si requis pour la compatibilité avec les anciennes versions, car ils ne supportent pas la coloration syntaxique et peuvent être moins lisibles.
• Placez une ligne vide avant et après les blocs de code clôturés pour améliorer la lisibilité dans le Markdown brut.

Fonctionnalités spéciales

• Certaines plateformes prennent en charge des identifiants de langage supplémentaires tels que diff pour montrer les modifications de code, ce qui met en évidence les lignes ajoutées ou supprimées lors des revues de code.
• Pour afficher des backticks à l’intérieur d’un bloc de code, enveloppez le bloc avec un nombre supérieur de backticks (par ex. quatre backticks pour afficher trois backticks à l’intérieur).

Résumé rapide

Utilisez des blocs de code clôturés avec un identifiant de langage pour une meilleure lisibilité et une coloration syntaxique optimale. Réservez le code inline pour les petits extraits et évitez les blocs indentés sauf si nécessaire pour la compatibilité.

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

Coloration syntaxique des Diff

La coloration syntaxique des diff vous permet de montrer clairement les modifications de code — utile dans la documentation, les revues de code et les blogs techniques.

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

Exemple :

- ancienne ligne qui sera supprimée
+ nouvelle ligne qui sera ajoutée
  ligne inchangée

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

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 coloration diff ne colore que des lignes entières en fonction du caractère initial ; elle ne met pas en évidence les modifications inline au sein d’une ligne.

Astuce : La coloration diff est largement supportée sur GitHub, GitLab et la plupart des renderers Markdown, ce qui en fait un choix fiable pour communiquer les changements de code.

Langages supportés pour la coloration syntaxique

La liste exacte des langages supportés dépend du renderer ou de la plateforme que vous utilisez. Markdown transmet l’identifiant de langage au moteur de rendu, qui applique la coloration syntaxique appropriée. Cela est important lors de la conversion de HTML vers Markdown avec Python, car les balises <code> portant des attributs de classe de langage (par ex. class="language-python") correspondent directement à ces identifiants dans le bloc clôturé.

Langages couramment supportés 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 & Configuration : markdown, ini, toml, dockerfile, makefile
• Spécial : diff, mermaid, geojson, topojson, stl (pour les diagrammes et visualisations de données sur GitHub) — l’identifiant mermaid en particulier permet le rendu complet de diagrammes sur les plateformes supportées ; voir le Guide de démarrage rapide et aide-mémoire Mermaid pour une référence syntaxique complète et un guide de configuration Hugo
• 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 supportés par la plupart des renderers :

Remarque : La plupart des renderers ignorent la casse pour les noms de langages. Si vous utilisez un identifiant non supporté, le bloc de code sera rendu en texte brut.

Pour trouver la liste complète des langages supportés :

• GitHub : Utilise Linguist, supportant des centaines de langages.
• VS Code & nombreux renderers web : Utilisent highlight.js ou Pygments — consultez leur documentation pour des listes exhaustives.
• Bitbucket : Fait référence aux modes CodeMirror et aux lexers Pygments.

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

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

1. Nom de fichier dans l’étiquette du bloc de code (Syntaxe Meta)

Certains moteurs Markdown (certains générateurs de sites statiques et plateformes de documentation) supportent une syntaxe meta où vous ajoutez le nom de fichier après le langage, séparé par deux-points :

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

Cela affiche le nom de fichier au-dessus ou à côté du bloc de code. Le renderer Hugo de ce site ne le supporte pas :

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

Remarque : Ceci n’est pas supporté sur le Markdown Flaveur GitHub.

2. Titre de nom de fichier manuel ou code inline

Pour une compatibilité universelle (incluant GitHub, Stack Overflow et la plupart des renderers Markdown), placez le nom de 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 de fichier au bloc de code.

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

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

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

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

Résumé de 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 plus de clarté lors du partage entre plateformes.

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

Pour afficher des clôtures de backticks à l’intérieur d’un bloc de code — par exemple lors de l’écriture de documentation sur le Markdown lui-même — imbriquez le bloc dans un nombre supérieur de backticks :

````markdown
```python
# Cette clôture de triple backtick est à l'intérieur d'une clôture de quatre backticks
print("hello")
```
````

L’utilisation de quatre backticks comme clôture externe vous permet d’afficher des exemples de triples backticks à l’intérieur, ce qui est pratique pour les tutoriels et aides-mémoires Markdown.

Spécifique à Hugo : Le shortcode Highlight

Si vous utilisez Hugo, le shortcode intégré highlight offre plus de contrôle que les blocs clôturés simples, incluant les numéros de ligne et les lignes surlignées :

{{< 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 ligne
• hl_lines=2 4 — surligner les lignes 2 et 4
• linenostart=10 — commencer la numérotation des lignes à 10

Ceci est particulièrement utile dans les tutoriels ou la documentation où vous souhaitez attirer l’attention sur des lignes spécifiques. Consultez l’Aide-mémoire Markdown pour plus de fonctionnalités de formatage, et l’Aide-mémoire Hugo pour une référence plus large sur les commandes et modèles Hugo.

Liens utiles

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