Les images en Markdown ressemblent presque aux liens, avec un caractère en plus au début. Ce petit point d'exclamation est facile à oublier, mais il change tout : au lieu de créer un lien cliquable, Markdown intègre l'image directement dans le document.

La syntaxe de base prend cinq secondes à comprendre. Les détails prennent plus de temps : chemins locaux, texte alternatif, taille des images, légendes, comportement sur GitHub, intégrations Obsidian, et ce qui se passe quand le fichier est déplacé.

Ce guide couvre la version pratique, de la syntaxe dont vous avez besoin tous les jours jusqu'aux cas particuliers qui finissent souvent sur Stack Overflow.

La syntaxe de base

La syntaxe Markdown standard pour une image est :

![Texte alternatif](./image.png)

Elle contient trois éléments :

! indique à Markdown qu'il s'agit d'une image, pas d'un lien.
[Texte alternatif] décrit l'image.
(./image.png) pointe vers le fichier image.

Par exemple :

![Interface du lecteur Markdown Fude](./images/fude-reader.png)

Si l'image se charge correctement, le lecteur affiche l'image. Si elle ne se charge pas, la plupart des moteurs de rendu affichent le texte alternatif à la place.

L'erreur la plus fréquente consiste à oublier le point d'exclamation :

[Logo](./logo.png)   ← lien vers le fichier image
![Logo](./logo.png)  ← affichage de l'image

La première ligne crée un lien. La seconde intègre l'image.

Images locales

La plupart des images Markdown utilisent un chemin relatif. Le chemin est résolu à partir de l'emplacement du fichier Markdown.

![Diagramme d'architecture](./assets/architecture.png)

Si votre document est ici :

docs/guide.md

Et votre image est ici :

docs/assets/architecture.png

Alors ./assets/architecture.png est correct.

Si l'image est dans le dossier parent :

![Logo](../logo.png)

Les règles sont les mêmes que pour les liens relatifs :

./ signifie "répertoire courant".
../ signifie "répertoire parent".
folder/image.png fonctionne aussi, mais ./folder/image.png rend l'intention plus claire.

Je recommande de garder les images près des fichiers Markdown qui les utilisent. Une structure simple fonctionne bien :

docs/
  guide.md
  images/
    diagram.png
    screenshot.png

Puis référencez-les ainsi :

![Diagramme système](./images/diagram.png)
![Capture d'écran de l'app](./images/screenshot.png)

Cela rend le document portable. Si vous déplacez tout le dossier docs, les chemins d'images continuent de fonctionner.

Images web

Vous pouvez également utiliser une URL complète :

![Logo Fude](https://fude.md/images/fude-logo.png)

C'est utile pour les assets distants, les images hébergées sur un CDN, les badges et les documentations qui doivent s'afficher sans fichiers locaux.

Le compromis : l'image dépend de l'URL distante. Si le serveur tombe, l'image disparaît. Si le propriétaire remplace l'image, votre document change sans que vous l'ayez modifié.

Pour une documentation durable, je préfère les images locales. Pour les badges et les assets dynamiques, les images distantes conviennent très bien.

Texte alternatif

Le texte alternatif n'est pas décoratif. Il décrit l'image pour les personnes qui ne peuvent pas la voir, et il fournit un texte de secours utile lorsque l'image ne se charge pas.

Un bon texte alternatif explique le contenu ou l'objectif de l'image :

![Capture d'écran de Fude affichant un document Markdown avec un tableau](./fude-table.png)

Un texte alternatif faible se contente de répéter qu'une image existe :

![Image](./fude-table.png)
![Capture d'écran](./fude-table.png)

Si l'image est purement décorative et n'ajoute aucune information, vous pouvez laisser le texte alternatif vide :

![](./divider.png)

Mais faites-le volontairement. La plupart des images dans une documentation ne sont pas décoratives. Les diagrammes, captures d'écran, graphiques et interfaces ont généralement besoin d'un texte alternatif utile.

Titres d'image

Comme les liens, les images peuvent recevoir un titre facultatif :

![Lecteur Fude](./fude-reader.png "Fude affichant un fichier Markdown local")

Le titre apparaît comme une infobulle dans certains moteurs de rendu. Le support est incohérent, surtout sur les appareils tactiles, donc ne mettez pas d'information essentielle dedans.

Utilisez le texte alternatif pour le sens. Utilisez le titre seulement pour une petite note supplémentaire.

Formats d'image

Markdown lui-même ne se soucie pas de savoir si l'image est en PNG, JPG, SVG, WebP, AVIF ou GIF. Le moteur de rendu, lui, s'en soucie.

Choix courants :

Format	Idéal pour	Notes
PNG	Captures d'écran, UI, diagrammes	Net, fiable, souvent plus lourd
JPG	Photos	Léger, mais avec perte
SVG	Logos, diagrammes vectoriels	Excellent quand le rendu l'autorise
WebP	Images web	Léger, largement supporté
AVIF	Images web très compressées	Excellente compression, pas universel partout
GIF	Animations simples	Lourd ; à utiliser avec parcimonie

Pour des fichiers Markdown lus localement ou stockés dans un dépôt, PNG reste souvent le choix le plus sûr pour les captures d'écran et les diagrammes.

Redimensionner les images

Le Markdown standard n'a pas de syntaxe pour définir la largeur ou la hauteur d'une image.

Ceci ne fonctionne pas en Markdown standard :

![Logo](./logo.png =200x100)

Certains outils supportent des extensions personnalisées de ce type, mais elles ne sont pas portables.

La solution portable la plus courante consiste à utiliser du HTML :

<img src="./logo.png" alt="Logo" width="200" />

Cela fonctionne dans beaucoup de moteurs de rendu Markdown, y compris GitHub, mais pas dans tous. Certaines applications désactivent le HTML brut pour des raisons de sécurité ou de cohérence.

Si vous voulez que votre document fonctionne partout, redimensionnez le fichier image lui-même avant de le référencer :

![Logo](./logo-small.png)

C'est moins sophistiqué, mais plus fiable.

Légendes

Le Markdown standard n'a pas de syntaxe native pour les légendes d'image.

La solution la plus simple consiste à ajouter un paragraphe en italique juste sous l'image :

![Vue de lecture Fude](./fude-reading-view.png)

*Fude affichant un document Markdown local.*

C'est lisible dans le fichier Markdown brut et cela fonctionne presque partout.

Si votre moteur de rendu supporte le HTML, vous pouvez utiliser <figure> et <figcaption> :

<figure>
  <img src="./fude-reading-view.png" alt="Vue de lecture Fude" />
  <figcaption>Fude affichant un document Markdown local.</figcaption>
</figure>

C'est plus sémantique en HTML, mais moins portable dans les outils Markdown qui suppriment le HTML brut. Pour des notes et des README, je choisis généralement le paragraphe en italique.

Images cliquables

Une image n'est pas cliquable par défaut. Pour la rendre cliquable, enveloppez la syntaxe d'image dans un lien :

[![Logo Fude](./fude-logo.png)](https://fude.md)

Décomposons :

![Logo Fude](./fude-logo.png) affiche l'image.
[...](https://fude.md) transforme cette image en lien vers l'URL.

Ce modèle est fréquent pour les badges :

[![Build Status](https://img.shields.io/badge/build-passing-green)](https://github.com/user/repo/actions)

Si vous avez déjà lu le guide sur les liens Markdown, c'est la même syntaxe avec une image à l'intérieur du texte du lien.

Images dans les tableaux

Les images peuvent apparaître dans des tableaux Markdown parce qu'elles sont du contenu en ligne :

| Produit | Aperçu |
| --- | --- |
| Fude | ![Icône Fude](./fude-icon.png) |

Cela fonctionne dans de nombreux moteurs de rendu, y compris GitHub.

Mais utilisez-le avec prudence. Les grandes images dans les tableaux rendent le tableau difficile à lire, surtout sur petit écran. Si l'image a besoin d'espace, placez-la en dehors du tableau et mettez plutôt un lien vers elle dans le tableau.

Images en base64

Techniquement, vous pouvez intégrer une image directement dans Markdown avec une URL de données :

![Petite icône](data:image/png;base64,iVBORw0KGgo...)

Cela rend le fichier Markdown autonome, mais aussi laid, énorme et difficile à modifier.

J'évite les images base64 sauf pour de très petits assets générés ou des fixtures de test. Pour une écriture normale, gardez l'image dans un fichier séparé.

Les images sur GitHub

GitHub supporte la syntaxe Markdown standard pour les images dans les README, issues, pull requests, wikis et fichiers .md rendus.

Ce qui fonctionne bien :

Les chemins relatifs comme ![Diagramme](./docs/diagram.png).
Les URL distantes comme ![Badge](https://img.shields.io/...).
Les images SVG, lorsqu'elles sont servies de manière sûre.
Les images cliquables avec [![alt](image)](url).
Les balises HTML <img> pour redimensionner, comme <img src="./logo.png" width="200" alt="Logo">.

Quelques spécificités GitHub :

Les chemins sont résolus par rapport au fichier Markdown, pas par rapport à la racine du dépôt.
Glisser une image dans une issue GitHub l'upload et insère une URL générée.
Les images file:// ne fonctionnent pas. GitHub ne peut pas lire les fichiers de votre ordinateur.
Si une image fonctionne en local mais pas sur GitHub, vérifiez la casse. macOS est souvent insensible à la casse ; GitHub est sensible à la casse.

Les images dans Fude

Dans Fude, les images Markdown standard sont conçues pour s'afficher proprement :

Les images locales relatives fonctionnent depuis l'emplacement du fichier Markdown.
Les images locales depuis la racine, comme /images/logo.png, sont résolues via le chemin d'asset sécurisé de Fude.
Les images web distantes s'affichent comme des images normales.
Les images en URL de données s'affichent lorsqu'elles utilisent un type d'image sûr.
Les sources non supportées comme file://, blob: et javascript: ne sont pas rendues comme des images actives.

Fude traite aussi l'affichage des images comme une préférence de lecture. Vous pouvez masquer les images, afficher les images Markdown standard, ou activer le mode HTML d'image sanitizé quand vous avez besoin de balises d'image en HTML brut.

Le point important : Fude ne transmet pas de chemins locaux arbitraires au moteur de rendu. Les images locales passent par un canal d'asset contrôlé, ce qui garde l'expérience de lecture utile sans transformer Markdown en accès libre au système de fichiers.

Les images dans Obsidian

Obsidian supporte les images Markdown standard :

![Capture d'écran](./screenshot.png)

Il supporte aussi les intégrations de type wiki :

![[screenshot.png]]

La syntaxe wiki est plus courte et fonctionne très bien dans un vault Obsidian, mais ce n'est pas du Markdown standard. Si vous prévoyez de lire le même fichier dans GitHub, Fude, VS Code ou un générateur de site statique, utilisez la syntaxe standard.

Obsidian supporte aussi sa propre syntaxe de taille d'image :

![[screenshot.png|400]]

Pratique dans Obsidian, non portable ailleurs.

Résoudre les problèmes courants

"Mon image s'affiche comme un lien"

Vous avez probablement oublié le point d'exclamation :

[Alt](./image.png)   ← lien
![Alt](./image.png)  ← image

"Mon image locale ne se charge pas"

Vérifiez le chemin depuis le fichier Markdown, pas depuis la racine du projet.

Si votre fichier est docs/guide.md et votre image est docs/images/chart.png, utilisez :

![Graphique](./images/chart.png)

Pas :

![Graphique](./docs/images/chart.png)

Ce second chemin ne fonctionne que si le fichier Markdown se trouve à la racine du projet.

"Ça marche sur mon Mac mais pas sur GitHub"

Vérifiez la casse :

![Logo](./images/logo.png)

ne trouvera pas :

images/Logo.png

sur un système sensible à la casse.

Vérifiez aussi les espaces. Vous pouvez les encoder :

![Diagramme](./images/user%20flow.png)

Ou entourer le chemin de chevrons :

![Diagramme](<./images/user flow.png>)

"Je n'arrive pas à redimensionner l'image"

Le Markdown pur ne permet pas de redimensionner les images. Utilisez l'une de ces options :

<img src="./image.png" alt="Texte alternatif" width="400" />

ou redimensionnez le fichier lui-même :

![Texte alternatif](./image-400px.png)

La deuxième option est plus portable.

"Le chemin de mon image contient des parenthèses"

Les parenthèses peuvent perturber le parseur, car ) ferme la destination de l'image.

Utilisez l'encodage URL :

![Graphique](./images/report%20%28final%29.png)

Ou utilisez des chevrons :

![Graphique](<./images/report (final).png>)

Référence rapide

# Image de base
![Texte alternatif](./image.png)

# Image avec titre
![Texte alternatif](./image.png "Titre facultatif")

# Image distante
![Texte alternatif](https://example.com/image.png)

# Texte alternatif vide pour une image décorative
![](./divider.png)

# Image cliquable
[![Texte alternatif](./image.png)](https://example.com)

# Légende simple
![Texte alternatif](./image.png)

*Texte de légende.*

# Redimensionner avec HTML
<img src="./image.png" alt="Texte alternatif" width="400" />

# Chemin avec espaces
![Texte alternatif](<./images/mon image.png>)

La syntaxe Markdown pour les images est simple, mais les images exposent tout ce qui rend Markdown pratique : chemins, portabilité, accessibilité et différences entre moteurs de rendu.

S'il faut retenir une règle, retenez celle-ci : gardez les images près des fichiers Markdown qui les utilisent, et écrivez le texte alternatif comme si l'image pouvait ne pas se charger.

Pour d'autres guides Markdown, consultez les articles sur les liens, les tableaux, et les lignes horizontales.

Si vous cherchez un lecteur Markdown qui gère proprement les images locales, essayez Fude.

📌 Télécharger Fude

Comment ajouter des images en Markdown