12. Comment ajouter des images dans une page MDX

Comment ajouter des images dans une page MDX

La méthode simple pour afficher des images dans votre documentation

Pourquoi ajouter des images ?

Les images rendent une documentation plus claire et plus agréable.

Elles permettent d’illustrer un concept, de montrer une interface ou d’expliquer une étape visuellement.

Mintlify supporte très bien les images, mais il faut respecter quelques règles simples.

Où placer vos images ?

Vous pouvez placer vos images dans :

• le dossier public/ de votre projet

• un sous‑dossier comme public/images/

• un hébergement externe (URL directe)

Mintlify recommande d’utiliser le dossier public/ pour garder un site propre et organisé.

Comment afficher une image dans une page MDX ?

Dans une page MDX, une image s’affiche simplement en utilisant la syntaxe Markdown classique :

Format général :

• une ligne pour l’image

• un texte alternatif clair

• un chemin propre

Mintlify gère automatiquement l’affichage responsive.

Comment organiser vos images ?

Pour garder un projet propre, utilisez une structure simple :

• créez un dossier public/images

• classez vos images par thème ou par page

• utilisez des noms de fichiers courts et explicites

• évitez les espaces dans les noms de fichiers

Une bonne organisation facilite la maintenance de votre documentation.

Erreurs fréquentes

• utiliser des chemins trop longs ou incorrects

• mettre des images dans des dossiers différents

• utiliser des noms de fichiers avec des espaces

• oublier de publier les images vers GitHub

• utiliser des images trop lourdes

Une image mal placée ou mal nommée ne s’affichera pas.

Conseils pratiques

• utilisez des images légères pour un chargement rapide

• gardez une résolution suffisante pour la lisibilité

• vérifiez l’affichage dans l’aperçu Mintlify

• testez la page après publication sur Vercel

Une image bien intégrée améliore la compréhension du lecteur.

Résumé

Ajouter une image dans une page MDX est simple :

placez l’image dans public/, utilisez un chemin propre et vérifiez l’affichage.

Une bonne organisation évite les erreurs et garde votre documentation claire.

Pour aller plus loin

• Documentation Mintlify : https://mintlify.com/docs

• Bonnes pratiques d’images web : https://developer.mozilla.org