Les blocs de code Markdown - fiche de référence et exemples d'utilisation

Les blocs de code Markdown sont simples

Sommaire

Ici, je passe en revue les options de blocs de code dans Markdown.

page wiki d’exemple avec un bloc de code

Blocs de code Markdown

Les blocs de code Markdown sont une façon d’afficher du code ou du texte préformaté dans les documents Markdown, en préservant le formatage et en permettant, le cas échéant, la mise en évidence de la syntaxe. Il existe deux types principaux de formatage de code dans Markdown : le code inline et les blocs de code.

Types de blocs de code Markdown

Type Exemple de syntaxe Cas d’utilisation Mise en évidence de la syntaxe Notes
Code inline `code` Petits extraits au sein d’un texte Non Pour un seul mot ou une commande
Bloc indenté (4 espaces ou 1 tabulation) Code multi-ligne (ancien style) Non Non recommandé pour une utilisation moderne
Bloc délimité code

Principales différences

  • Le code inline utilise des backticks simples (`) et est utilisé pour de courts 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 évidence de la syntaxe et sont moins courants dans le Markdown moderne.
  • Les blocs de code délimités utilisent trois backticks (```) ou des tilde (~~~) avant et après le code. C’est la méthode recommandé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 évidence de la syntaxe.
    • Ils préservent le formatage et prennent en charge le code multi-ligne.

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

Lorsque nous avons le texte Markdown suivant :

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

Le texte rendu ressemblera à :

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

Meilleures pratiques pour l’utilisation des blocs de code Markdown

  • Utilisez les blocs de code délimités (trois backticks) pour le code multi-ligne 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 évidence de la syntaxe (par exemple, ``````python).
  • Utilisez le code inline pour de courts extraits ou des commandes au sein du texte.
  • Évitez les blocs de code indentés sauf si nécessaire pour la compatibilité avec des anciens systèmes, car ils ne prennent pas en charge la mise en évidence 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é du 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 peut mettre 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, entourez le bloc d’un nombre plus élevé de backticks (par exemple, quatre backticks pour afficher trois backticks).

OutTake

Fonctionnalité Code Inline Bloc Indenté Bloc Délimité
Support multi-ligne Non Oui Oui
Mise en évidence de la syntaxe Non Non Oui
Recommandé pour le code Non Non Oui
Facilité d’utilisation Facile Moyenne Facile

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

Mise en évidence de la syntaxe diff

Pour utiliser efficacement la mise en évidence de la syntaxe diff dans les blocs de code Markdown, suivez ces étapes :

  • Utilisez des blocs de code délimités avec des triple backticks (```) pour commencer et terminer votre bloc.
  • Spécifiez diff comme identifiant de langage immédiatement après les backticks ouvrants. Cela active la mise en évidence des différences, similaire à ce que vous voyez dans les messages de commit Git ou les demandes de tirage.

Exemple :

- ligne ancienne qui sera supprimée
+ nouvelle ligne qui sera ajoutée
 ligne non modifiée
  • Les lignes commençant par - seront mises en évidence comme des suppressions (généralement en rouge).
  • Les lignes commençant par + seront mises en évidence comme des ajouts (généralement en vert).
  • Les lignes sans préfixe ne seront pas spécialement mises en évidence.

Bonnes pratiques :

  • Utilisez ce format pour communiquer clairement les changements de code, les correctifs ou les suggestions dans la documentation, les revues de code ou les blogs techniques.
  • Placez une ligne vide avant et après votre bloc de code pour une meilleure lisibilité du Markdown brut.
  • Notez que la mise en évidence diff ne colore que les lignes entières en fonction du caractère initial ; elle ne met pas en évidence les changements inline au sein d’une ligne.

Conseil :
Cette méthode est largement prise en charge sur des plateformes comme GitHub, GitLab et de nombreux rendus Markdown, ce qui en fait un choix fiable pour partager visuellement les changements de code.

Langages pris en charge

Les blocs de code Markdown prennent en charge une large variété de langages pour la mise en évidence de la syntaxe, mais l’ensemble exact des langages pris en charge dépend du rendu ou de la plateforme que vous utilisez. Le Markdown lui-même ne définit pas quels langages sont pris en charge ; il transmet simplement l’identifiant de langage au moteur de rendu, qui applique alors la mise en évidence de la syntaxe appropriée. Les fences de code Markdown eux-mêmes ne définissent pas un ensemble fixe de langages de programmation officiellement pris en charge. Au contraire, la liste des langages pris en charge dépend du moteur de rendu Markdown ou de la plateforme que vous utilisez (comme GitHub, GitLab, VS Code, Typora, Quarto, etc.).

Langages couramment pris en charge sur les principales plateformes (comme GitHub, VS Code, Bitbucket, Docusaurus, et ReadMe) incluent :

  • Web & Scripting : javascript (js), typescript (ts), html, css, json, xml, yaml, shell/bash (sh, bash, shell, zsh)
  • Programmation : python (py), java, c, c++, 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éciaux : 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 : Utilisez le nom du langage immédiatement après les triple backticks ouvrants :

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

Les langages suivants sont largement pris en charge par LA MAJORITÉ DES RENDEURS Markdown :

Langage Identifiant(s) courant(s)
Python python, py
JavaScript javascript, js
TypeScript typescript, ts
Java java
C c
C++ cpp, c++
C# csharp, cs, c#
Go go
Ruby ruby, rb
PHP php
Rust rust
Swift swift
Kotlin kotlin
HTML html
CSS css
Shell/Bash shell, bash, sh, zsh
SQL sql
JSON json
YAML yaml, yml
Markdown markdown, md
Perl perl
Lua lua
R r
Matlab matlab
Makefile makefile

Note : L’identifiant réel peut varier (par exemple, js vs. javascript). La plupart des moteurs de rendu sont insensibles à la casse pour les noms de langage.

Pour trouver la liste complète des langages pris en charge :

  • GitHub : Utilise Linguist pour la mise en évidence, prenant 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.

Points clés :

  • La plupart des plateformes prennent en charge tous les langages de programmation, de scripting et de markup majeurs.
  • Certaines plateformes prennent également en charge des formats de diagramme et de données (comme mermaid, geojson).
  • L’identifiant de langage est généralement insensible à la casse, mais devrait être en minuscules pour la meilleure compatibilité.
  • Si vous utilisez un identifiant de langage non pris en charge, le bloc de code sera rendu en texte brut.

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

Pour spécifier un nom de fichier dans un bloc de code Markdown, vous avez plusieurs options, mais la méthode dépend de la plateforme et du rendu :

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

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

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

Cela affichera le nom de fichier (par exemple, app.js) au-dessus ou à côté du bloc de code, selon le rendu. Et ce site’ rendu hugo ne le fait pas :

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

Note : Cela n’est pas pris en charge sur toutes les plateformes (par exemple, le Markdown favorisé par GitHub ne prend pas actuellement en charge cette fonctionnalité).

2. Titre ou code inline en gras avec le nom de fichier

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

**`app.js`**

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

Ou :

#### `app.js`

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

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

3. Nom de fichier comme commentaire dans le code

En alternative, vous pouvez inclure le nom de fichier comme commentaire à l’intérieur du bloc de code lui-même :

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

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

Résumé et bonnes pratiques

Méthode Pris en charge sur GitHub Pris en charge sur Docs/Blogs Universel
Syntaxe méta (ex. :app.js) Non Parfois Non
Titre/code inline au-dessus Oui Oui Oui
Commentaire dans le code Oui Oui Oui

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

Liens utiles