Images
Découvrez comment Jamdesk gère la taille des images, les légendes, les variantes clair/sombre et les formats pris en charge pour des visuels nets.
Jamdesk affiche les images avec des coins arrondis et un espacement cohérent. Placez 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 familière  :
Les chemins partent de la racine de votre projet. Une image située dans your-docs/images/screenshot.webp est référencée sous /images/screenshot.webp.
Dimensions des images
Ajoutez =LARGEURxHAUTEUR après l'URL de l'image (séparé par un espace) pour contrôler la taille :
Définissez une seule dimension et l'autre s'adapte proportionnellement :
Ceci est utile lorsque vous voulez une colonne cohérente de captures d'écran à la même largeur, ou lorsque vous devez 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 le texte de la légende en dessous. Il fonctionne avec n'importe quel contenu à l'intérieur, pas seulement des images.
Mode clair/sombre
Les sites de documentation ont souvent besoin de variantes d'image différentes pour chaque thème de couleur : un logo sur fond blanc apparaît mal en mode sombre.
L'attribut srcDark
L'approche la plus simple. Jamdesk change la source de l'image selon le thème actif :
<img
src="/_jd/images/logo-light.webp?v=mrtvmucv"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>Le navigateur ne charge que l'image correspondant au thème de couleur actuel.
L'élément HTML <picture>
Si vous avez besoin de HTML standard fonctionnant 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=mrtvmucv" alt="Company logo" />
</picture>L'approche <picture> respecte le réglage du thème de couleur du système d'exploitation. L'attribut srcDark répond plutôt au bouton de thème de Jamdesk, ce qui est généralement ce que l'on souhaite pour la documentation.
Formats pris en charge
| Format | Idéal pour | Remarques |
|---|---|---|
| PNG | Captures d'écran, interfaces | Qualité sans perte, transparence prise en charge. Fichiers plus volumineux. |
| JPEG | Photographies | Bonne compression, pas de prise en charge de la transparence. |
| SVG | Icônes, diagrammes, logos | Format vectoriel qui s'adapte à toute taille sans perte de qualité. Fichier très léger. |
| GIF | Animations simples | Peut vite devenir volumineux. Envisagez des boucles .mp4 courtes 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. Pour la transparence, WebP la gère aussi, donc le PNG n'est plus nécessaire.
Bonnes pratiques
Le texte alternatif a deux fonctions : les lecteurs d'écran l'utilisent pour l'accessibilité, et il s'affiche comme espace réservé si l'image ne 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 d'arrière-plan, séparateurs), utilisez un texte alternatif vide : .
Les images lourdes ralentissent le chargement des pages, surtout sur les connexions mobiles. Tailles cibles :
- Captures d'écran/interfaces : PNG ou WebP, moins de 500 Ko
- Photos : JPEG ou WebP, moins de 200 Ko
- Icônes et diagrammes : SVG dans la mesure du possible
Squoosh et TinyPNG compressent les images sans perte de qualité visible. Passez vos captures d'écran par l'un de ces outils avant de les valider.
Ou laissez Jamdesk s'en charger au moment du build. Activez la conversion WebP automatique dans votre docs.json et chaque PNG ou JPG que vous validez sera optimisé à chaque build.
Des captures d'écran qui passent d'une largeur à l'autre paraissent désordonnées. Choisissez une largeur de capture standard (1200 px fonctionne bien) et utilisez-la dans toute votre documentation. Jamdesk redimensionne automatiquement les images pour s'adapter à la zone de contenu, donc des dimensions source cohérentes produisent des résultats affichés cohérents.
Jamdesk génère automatiquement une carte sociale de marque en 1200×630 pour chaque page, que vous pouvez remplacer par page avec og:image dans le frontmatter. Après un build, passez l'URL de la page dans l'outil gratuit OpenGraph Preview pour voir le rendu de la carte sur X, Facebook, LinkedIn, Slack, Discord, et plus encore. Consultez SEO Optimization pour la configuration complète.
Organisation des fichiers
Regroupez les images dans des sous-répertoires qui reflètent la structure de votre contenu. Cela facilite leur repérage à mesure que votre documentation grandit :
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.jsonRéférencez-les avec le chemin complet depuis la racine de votre projet :
Évitez les espaces dans les noms de fichiers image. Utilisez plutôt des tirets : api-response.webp, et non api response.webp.