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

Les blocs de code délimités contiennent du code source sur plusieurs lignes en Markdown. Le jeton situé après la clôture d’ouverture est une balise de langage, et seul le moteur de rendu décide ce que cette balise met en évidence.

Ce guide fait partie de Outils de documentation en 2026 : Markdown, LaTeX, PDF et flux de travail d’impression.

GitHub consulte la balise de langage avec Linguist et les mots-clés dans languages.yml. Hugo 0.164 transmet la même balise à Chroma. Une balise que Chroma ne connaît pas reste un bloc de code, affiché en texte brut. Les titres, les tableaux et les autres types de blocs figurent dans Aide-mémoire Markdown.

Aperçu des blocs de code Markdown

Markdown propose trois façons de marquer le code. Le code en ligne est une portion à l’intérieur d’un paragraphe. Un bloc indenté et un bloc délimité sont tous deux sur plusieurs lignes, et seul le bloc délimité porte une balise de langage.

Un bloc indenté ne peut pas porter de langage. CommonMark considère une ligne indentée de quatre espaces comme du code et ne donne rien à l’outil de mise en évidence pour la correspondance, c’est pourquoi le bloc délimité est la forme à utiliser lorsque l’exemple doit être coloré.

Un délimiteur est une ligne d’au moins trois accents graves (backticks) ou trois tildes, le code, puis une ligne de fermeture du même caractère, au moins aussi longue. La ligne de fermeture n’a pas de chaîne d’information. Pour afficher un délimiteur à trois accents graves à l’intérieur de l’exemple, ouvrir et fermer avec quatre accents graves. La documentation de GitHub sur les blocs de code demande une ligne vide avant et après le délimiteur pour que le fichier brut soit plus lisible ; le délimiteur reste analysable sans cette ligne vide.

Lorsque la source suivante est stockée en Markdown :

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

ce site Hugo l’affiche ainsi :

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

Le code en ligne utilise la même règle des accents graves à une plus petite échelle. Une paire d’accents graves uniques suffit pour git status. Lorsque la portion elle-même contient un accent grave, utiliser deux accents graves de chaque côté :

`` `code` ``

Mise en évidence de la syntaxe Diff

Un délimiteur balisé diff est la manière dont un changement est affiché sous forme de texte. L’analyseur lexical Chroma de Hugo accepte diff et udiff. GitHub met en évidence ce même identifiant depuis sa liste de langages.

- old line that will be removed
+ new line that will be added
  unchanged line

Les lignes commençant par - prennent le style de suppression, et les lignes commençant par + prennent le style d’insertion. Une ligne n’ayant aucun préfixe est du texte ordinaire dans cet analyseur. La coloration concerne toute la ligne. Un mot modifié au milieu d’une ligne n’est pas marqué séparément.

Identifiants de langage

Le premier mot de la chaîne d’information est le langage. La documentation de Hugo considère ce mot comme insensible à la casse. Si Chroma n’a pas d’analyseur lexical pour lui, Hugo 0.164 émet un <pre><code class="language-…"> brut sans enveloppe de mise en évidence. Un rendu local de notalang a fait cela. guessSyntax est faux par défaut, et la documentation de Hugo indique que seulement cinq analyseurs lexicaux implémentent la détection automatique, donc une balise omise reste en texte brut plutôt qu’un langage supposé.

Le HTML produit par ces délimiteurs utilise la classe language-python et le même jeton. Cette classe est ce qu’un convertisseur doit préserver lorsqu’il transforme une page mise en évidence à nouveau en Markdown, ce qui correspond au mappage couvert dans Convertir le HTML en Markdown avec Python.

Les identifiants ci-dessous sont ceux listés pour ces langages dans le tableau Chroma de Hugo. Sur un rendu Hugo 0.164, cs, yml et markdown étaient également colorés, même là où le tableau publié affiche csharp, yaml et md.

Les sites GitHub Pages qui utilisent encore Jekyll pour la mise en évidence ont besoin de l’identifiant en minuscules. La documentation de GitHub elle-même énonce cette exigence séparément du rendu sur github.com.

GitHub traite également certains délimiteurs comme des diagrammes plutôt que du code coloré : mermaid, geojson, topojson et stl. Le tableau Chroma de Hugo ne liste pas mermaid. Sur un site Hugo, le délimiteur reste un texte source jusqu’à ce qu’un hook de rendu, un shortcode ou un script le dessine. Le Guide de démarrage rapide et l’aide-mémoire Mermaid couvre cette configuration.

Spécifier un nom de fichier

Rien dans CommonMark ni dans la documentation de GitHub sur les blocs de code ne transforme la chaîne d’information en nom de fichier. Les options de mise en évidence de Hugo sont des paires d’accolades telles que {linenos=inline}. Elles n’incluent pas de champ nom de fichier.

Deux-points après le langage

Certains générateurs traitent js:app.js comme un langage plus un nom :

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

GitHub ne le fait pas. Hugo 0.164 conserve le jeton entier comme classe de l’élément de code (language-js:app.js) et n’imprime pas de nom de fichier. Les dialectes qui ajoutent une signification au-delà du premier mot font l’objet de la comparaison dans GFM vs CommonMark vs Pandoc Markdown.

Nom au-dessus du délimiteur

Une ligne de code en ligne en gras au-dessus du délimiteur affiche le nom sur GitHub, sur ce site, et dans d’autres moteurs de rendu CommonMark :

**`app.js`**

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

Un titre fonctionne de la même manière :

#### `app.js`

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

Nom à l’intérieur de l’exemple

Un commentaire dans la première ligne voyage avec le code lorsque quelqu’un copie le bloc :

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

Échapper les accents graves (backticks)

Quatre accents graves à l’extérieur affichent un délimiteur à trois accents graves, ce qui est le modèle pour une page documentant le Markdown :

````markdown
```python
# This triple-backtick fence is inside a four-backtick fence
print("hello")
```
````

Le délimiteur de fermeture doit être du même caractère que celui d’ouverture, et au moins aussi long. Un fermant plus court termine le bloc trop tôt et laisse le reste de l’exemple en paragraphes ordinaires.

Options de mise en évidence Hugo

Le config.toml de ce site n’a pas de bloc [markup.highlight], donc les valeurs par défaut de Hugo s’appliquent : les blocs délimités sont mis en évidence, le style est monokai, les styles sont écrits en ligne (noClasses vrai), et les numéros de ligne sont désactivés. Hugo 0.164 colore toujours un délimiteur qui ne demande qu’un langage, comme l’exemple Python ci-dessus.

Les numéros de ligne et les lignes mises en évidence sont des options entre accolades après le langage. Ce délimiteur demande des numéros en ligne et marque la ligne 2 :

```python {linenos=inline hl_lines=[2]}
def hello():
    print("Hello, world!")
```

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

linenos accepte inline, table, true ou false. hl_lines est une liste de numéros de ligne ou de plages. linenostart définit le premier numéro affiché. Les mêmes clés sont insensibles à la casse. Le shortcode highlight les prend comme une seule chaîne entre guillemets, et cette chaîne a toujours rendu des numéros de ligne sur Hugo 0.164 :

{{< highlight python "linenos=true,hl_lines=2" >}}
def hello():
    print("Hello, world!")
{{< /highlight >}}

Pour déplacer les couleurs dans une feuille de style, définir noClasses sur false et générer le CSS. Hugo 0.164 accepte --mode et --modeSelector sur cette commande :

hugo gen chromastyles --style=monokai --mode=light > assets/css/highlight.css
hugo gen chromastyles --style=monokai --mode=dark --modeSelector > assets/css/highlight-dark.css

--modeSelector scope chaque règle sous une classe de niveau supérieur telle que .dark .chroma. La liste des drapeaux est hugo gen chromastyles --help.

Lorsque le délimiteur semble incorrect

Vérifier l’élément généré avant de modifier l’exemple. Sur cette version de Hugo, un langage connu est un div.highlight dont l’élément de code a data-lang défini sur l’identifiant. Un identifiant inconnu est un pre et code nu avec class="language-…", ce que notalang a produit.

Si le nom app.js est manquant et que la classe est language-js:app.js, la forme avec deux-points a été utilisée. Déplacer le nom sur la ligne au-dessus du délimiteur.

Si les délimiteurs d’un tutoriel apparaissent comme des paragraphes lâches, le délimiteur externe est de la même longueur que le délimiteur interne. Allonger le délimiteur externe.

Si une courte commande avale l’accent grave au milieu d’une phrase, la portion a besoin d’une paire d’accents graves plus longue que le caractère qu’elle contient.

Liens utiles

• https://www.markdownguide.org/extended-syntax/
• https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks
• https://gohugo.io/content-management/syntax-highlighting/