Conversion automatique des images

Jamdesk peut convertir les images PNG et JPG au format WebP lors des builds. Les fichiers WebP sont généralement 60 à 80 % plus légers que les originaux sans perte de qualité visible, ce qui permet à vos pages de se charger plus rapidement sans traitement manuel des images.

La fonctionnalité est désactivée par défaut. Activez-la dans votre docs.json.

Activer la fonctionnalité

Ajoutez le champ images.convertToWebp à votre docs.json :

{
  "images": {
    "convertToWebp": true
  }
}

C'est le seul paramètre. La page Paramètres du dashboard affiche l'état actuel sous Config Highlights, mais elle ne dispose pas de son propre interrupteur. docs.json fait office de source de vérité.

Ce qui est converti

Les images converties conservent leur nom de base et reçoivent une extension .webp. Chaque référence dans votre MDX, CSS personnalisé, JavaScript personnalisé et docs.json est réécrite automatiquement. Vous n'avez pas à modifier les chemins.

Ce qui reste au format original

Certaines images ne sont pas touchées même lorsque la conversion est activée.

Favicons. Tous les navigateurs ou clients de messagerie ne rendent pas les favicons WebP de manière fiable.

Les images pour les réseaux sociaux (og:image et twitter:image dans vos seo.metatags) restent également dans leur format d'origine. Les robots d'exploration comme Facebook, LinkedIn, WhatsApp et les anciennes versions de Twitter/X ne prennent pas tous en charge le WebP, et une carte de preview cassée est pire qu'un JPG légèrement plus lourd.

Les images inutilisées sont également épargnées. Si un fichier se trouve dans votre répertoire /images mais que rien dans votre MDX ou votre configuration n'y fait référence, l'original est tout de même téléversé sur le CDN, mais il n'est pas converti. Inutile de dépenser du CPU pour quelque chose qui n'est référencé nulle part.

Les images qui ne bénéficieraient pas de la conversion restent au format original. Si la sortie WebP serait plus volumineuse que le fichier source (fréquent avec des JPG déjà compressés et de très petits PNG), Jamdesk conserve l'original. Ces images apparaissent comme skipped dans les statistiques du build.

Un cas qui est converti : background.image. C'est un arrière-plan plein écran rendu par le navigateur, qui bénéficie donc du WebP comme n'importe quelle autre image.

Indicateur de progression du build

Lorsque la fonctionnalité est activée, votre build affiche une étape Optimisation des images dans la liste de progression du dashboard, entre « Building documentation » et « Uploading to CDN ». La CLI jamdesk deploy affiche la même étape dans sa sortie de progression dans le terminal. Lorsque la fonctionnalité est désactivée, l'étape n'apparaît pas du tout.

Mise en cache du build

Jamdesk stocke un hash de chaque image source dans le manifeste du build. Si un fichier n'a pas changé depuis le dernier build, la conversion est ignorée et le WebP mis en cache est réutilisé. Les temps de rebuild restent rapides même avec des centaines d'images.

Gestion des erreurs

Si la conversion échoue pour une seule image (fichier corrompu, mémoire insuffisante, format inattendu), l'original est conservé et le reste du build se poursuit. Votre documentation ne sera pas affectée par une erreur de conversion d'image.

Journaux du build

En plus de l'indicateur du dashboard, vos journaux de build incluent une ligne comme celle-ci :

Optimizing images... done (4 converted, 2 cached, 1 skipped, 0 failed, saved 1.2 MB)