Comment ajouter une image en Markdown :point d’exclamation, texte alternatif, chemin.

La syntaxe

![Alt text](path/to/image.png "Optional title")

• Le texte alternatif entre crochets décrit l’image aux lecteurs d’écran et s’affiche si l’image ne se charge pas. Écrivez ce que montre l’image, pas « image ».
• Le chemin va entre parenthèses. S’il contient des espaces, écrivez-les %20 ou entourez le chemin de chevrons.
• Le titre est un texte facultatif entre guillemets, généralement affiché en info-bulle au survol.

Le style par référence fonctionne aussi et évite de mettre de longues adresses dans le texte :

![Logo][logo]

[logo]: https://example.com/logo.png "DotMD logo"

Chemins relatifs et emplacement du fichier

Un chemin sans schéma est relatif au fichier Markdown, et non à l’endroit où vous avez ouvert l’application. Avec cette organisation de fichiers

docs/
  spec.md
  assets/
    flow.png

l’image dans spec.md s’écrit ![Flow](assets/flow.png). Depuis un fichier situé un dossier plus haut, écrivez docs/assets/flow.png, et depuis un dossier en dessous, ../assets/flow.png. Sur GitHub, un chemin qui commence par / est relatif à la racine du dépôt. Gardez les images à côté du document, dans un dossier assets, pour que déplacer le dossier déplace aussi les images.

Les noms de fichiers d’images sont sensibles à la casse sur les serveurs Linux, alors qu’un Mac ne l’est pas ; c’est une cause fréquente d’image qui marche en local et casse en ligne.

Comment fixer la taille de l’image

Markdown lui-même n’a pas de taille. Utilisez une balise HTML img avec une largeur ; la hauteur suit les proportions :

<img src="assets/screen.png" alt="Settings window" width="400">

La largeur et la hauteur sont en pixels, et un pourcentage comme width="50%" marche dans la plupart des applications. GitHub gère cette balise dans les README et les commentaires. Certaines applications acceptent aussi une taille dans le texte alternatif, comme ![Screenshot|400](assets/screen.png). Cette forme vient d’Obsidian et DotMD la lit, mais les autres applications afficheront le |400 comme faisant partie du texte alternatif : utilisez donc la balise HTML pour un fichier qui doit marcher partout. Dans une cellule de tableau, une barre verticale s’écrit \|.

Alignement et légendes

L’alignement et les légendes relèvent aussi du HTML. Pour centrer une image, mettez-la dans un paragraphe avec align :

<p align="center">
  <img src="assets/logo.png" alt="Logo" width="200">
</p>

Pour une légende, utilisez un figure avec un figcaption :

<figure>
  <img src="assets/flow.png" alt="Request flow" width="500">
  <figcaption>Figure 1. The request flow.</figcaption>
</figure>

Toutes les applications ne gardent pas ces balises ; GitHub en garde la plupart, et DotMD affiche les deux. Si vous voulez une légende qui marche partout, mettez plutôt une ligne en italique sous l’image : *Figure 1. The request flow.*.

Une image cliquable et d’autres astuces

Mettez l’image dans un lien pour la rendre cliquable :

[![Build status](https://example.com/badge.svg)](https://example.com/builds)

C’est ainsi que sont construits les badges en haut d’un README. Pour afficher une autre image en mode sombre, utilisez un élément picture avec un <source media="(prefers-color-scheme: dark)">, là où l’application le gère.

Texte alternatif, poids des fichiers et formats

Écrivez le texte alternatif comme si vous décriviez l’image au téléphone : Settings window with the Sync option turned on en dit plus que screenshot. Pour une image purement décorative, laissez les crochets vides afin qu’un lecteur d’écran l’ignore.

Utilisez PNG pour les captures d’écran et les diagrammes, JPEG pour les photos, SVG pour les logos et les dessins au trait, et gardez les fichiers légers : une capture de 6 Mo ralentit un README et un dépôt. La plupart des applications affichent aussi les GIF animés comme n’importe quelle autre image.

Pourquoi l’image ne s’affiche pas

• Le chemin est faux. Vérifiez-le depuis le dossier du fichier Markdown, et vérifiez la casse du nom de fichier.
• Un point d’exclamation manquant. Sans lui, vous obtenez un lien, pas une image.
• Une espace dans le chemin qui n’est pas échappée.
• Un fichier local dans une page en ligne. Un chemin vers un fichier de votre disque ne marche que sur votre disque.
• Une image distante bloquée. Certaines applications ne chargent les images du web qu’après votre autorisation.

Pour voir l’aspect d’une image, ouvrez le fichier dans un lecteur qui résout les chemins relativement au document. DotMD le fait : les images s’affichent au plus à la largeur de la colonne de texte, la balise HTML de largeur est respectée, et une capture collée dans l’éditeur est enregistrée dans un dossier assets à côté du fichier. La lecture est gratuite.

Questions sur les images en Markdown

Plus de questions