Images
Ajoutez des images à votre documentation avec la syntaxe markdown, le contrôle des dimensions, les légendes et la prise en charge des modes clair et sombre.
Jamdesk affiche les images avec des coins arrondis et un espacement cohérent. Déposez vos fichiers dans le répertoire /images et référencez-les avec la syntaxe markdown standard.
Les captures d'écran montrent l'interface en anglais.
Markdown standard
Utilisez la syntaxe habituelle  :
Les chemins partent de la racine de votre projet. Une image située à your-docs/images/screenshot.webp se référence par /images/screenshot.webp.
Dimensions des images
Ajoutez =LARGEURxHAUTEUR après l'URL de l'image (séparé par une espace) pour contrôler la taille :
Ne renseignez qu'une seule dimension et l'autre s'ajuste proportionnellement :
Pratique pour aligner une colonne de captures d'écran à la même largeur, ou pour réduire une image haute résolution à une taille d'affichage raisonnable.
Légendes
Enveloppez une image dans le composant <Frame> pour ajouter une bordure et une légende en dessous :
<Frame caption="Dashboard overview showing project statistics">
</Frame>
Frame dessine une bordure discrète autour de l'image et place la légende en dessous. Il fonctionne avec n'importe quel contenu, pas seulement les images.
Mode clair / mode sombre
Les sites de documentation ont souvent besoin de variantes d'image pour chaque thème — un logo sur fond blanc ne rend pas bien en mode sombre.
L'attribut srcDark
L'approche la plus simple. Jamdesk échange la source de l'image en fonction du thème actif :
<img
src="/_jd/images/logo-light.webp?v=mo97v0f0"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Le navigateur ne charge que l'image correspondant au thème courant.
L'élément HTML <picture>
Si vous voulez du HTML standard qui fonctionne aussi en dehors de Jamdesk, utilisez <picture> avec une media query :
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mo97v0f0" alt="Company logo" />
</picture>L'approche <picture> respecte le réglage de thème du système d'exploitation. L'attribut srcDark réagit au sélecteur de thème de Jamdesk, ce qui est généralement le comportement attendu pour une documentation.
Formats pris en charge
| Format | Idéal pour | Notes |
|---|---|---|
| PNG | Captures d'écran, interfaces | Qualité sans perte, transparence prise en charge. Fichiers plus volumineux. |
| JPEG | Photographies | Bonne compression, pas de transparence. |
| SVG | Icônes, schémas, logos | Format vectoriel — s'adapte à toute taille sans perte de qualité. Très léger. |
| GIF | Animations simples | Peut vite devenir volumineux. Privilégiez de courtes boucles .mp4 au-delà de quelques images. |
| WebP | Usage général | Plus léger que PNG et JPEG à qualité comparable. Fonctionne dans tous les navigateurs modernes. |
WebP offre le meilleur rapport taille/qualité pour la plupart des images de documentation. Si vous avez besoin de transparence, WebP la gère aussi — plus besoin de PNG.
Bonnes pratiques
Le texte alternatif a deux rôles : les lecteurs d'écran l'utilisent pour l'accessibilité, et il s'affiche comme repli quand l'image ne se charge pas. Décrivez ce que l'image montre réellement.
{/* Good -- says what's in the image */}
{/* Bad -- tells you nothing */}
Pour les images décoratives qui n'apportent pas d'information (motifs de fond, séparateurs), utilisez un texte alternatif vide : .
Les images lourdes ralentissent le chargement des pages, surtout sur mobile. Tailles cibles :
- Captures d'écran / interfaces : PNG ou WebP, moins de 500 Ko
- Photos : JPEG ou WebP, moins de 200 Ko
- Icônes et schémas : SVG dès que possible
Squoosh et TinyPNG compressent les images sans perte de qualité visible. Passez vos captures d'écran dans l'un de ces outils avant de committer.
Ou laissez Jamdesk s'en charger au moment du build. Activez la conversion WebP automatique dans votre docs.json et chaque PNG ou JPG committé est optimisé à chaque build.
Des captures d'écran qui changent de largeur d'une page à l'autre donnent un rendu brouillon. Choisissez une largeur de capture standard (1200 px fonctionne bien) et utilisez-la partout. Jamdesk redimensionne automatiquement les images pour les adapter à la zone de contenu : des dimensions sources cohérentes produisent un rendu cohérent.
Organisation des fichiers
Regroupez vos images dans des sous-répertoires qui reflètent la structure de votre contenu. Elles restent ainsi faciles à retrouver à mesure que la documentation grandit :
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
Référencez-les avec le chemin complet depuis la racine du projet :
Évitez les espaces dans les noms de fichiers. Utilisez des tirets : api-response.webp, pas api response.webp.