Conversión automática de imágenes

Jamdesk puede convertir imágenes PNG y JPG a formato WebP durante los builds. Los archivos WebP suelen ser entre un 60 y un 80 % más pequeños que los originales sin pérdida de calidad visible, por lo que tus páginas cargan más rápido sin necesidad de procesamiento manual de imágenes.

La función está desactivada de forma predeterminada. Actívala en tu docs.json.

Actívala

Añade el campo images.convertToWebp a tu docs.json:

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

Ese es el único interruptor. La página de Settings en el dashboard muestra el estado actual en Config Highlights, pero no tiene su propio interruptor. docs.json es la fuente de la verdad.

Qué se convierte

Las imágenes convertidas conservan su nombre base y obtienen la extensión .webp. Todas las referencias en tu MDX, CSS personalizado, JS personalizado y docs.json se reescriben automáticamente. No necesitas cambiar ninguna ruta.

Qué permanece como original

Algunas imágenes se dejan sin tocar incluso cuando la conversión está activada.

Favicons. No todos los navegadores ni clientes de correo electrónico renderizan los favicons WebP de forma fiable.

Las imágenes para redes sociales (og:image y twitter:image en tu seo.metatags) también permanecen en su formato original. Los rastreadores de redes sociales como Facebook, LinkedIn, WhatsApp y las versiones antiguas de Twitter/X no todos renderizan WebP, y una tarjeta de vista previa rota es peor que un JPG ligeramente más grande.

Las imágenes sin usar también quedan exentas. Si un archivo está en tu directorio /images pero nada en tu MDX o configuración lo referencia, el original se sigue subiendo al CDN, pero no se convierte. No tiene sentido gastar CPU en algo que nada enlaza.

Las imágenes que no se beneficiarían de la conversión permanecen como originales. Si el resultado en WebP fuera más grande que el archivo de origen (algo común en JPGs ya comprimidos y PNGs muy pequeños), Jamdesk conserva el original. Estas aparecen como skipped en las estadísticas del build.

Una cosa que sí se convierte: background.image. Es un fondo de pantalla completa renderizado por el navegador, así que se beneficia de WebP como cualquier otra imagen.

Indicador de progreso del build

Cuando la función está activada, tu build muestra un paso Optimizing images en la lista de progreso del dashboard, entre "Building documentation" y "Uploading to CDN". El CLI jamdesk deploy muestra el mismo paso en su salida de progreso en la terminal. Cuando la función está desactivada, el paso no aparece en absoluto.

Caché del build

Jamdesk guarda un hash de cada imagen de origen en el manifiesto del build. Si un archivo no ha cambiado desde el último build, omite la conversión y reutiliza el WebP en caché. Los tiempos de rebuild se mantienen rápidos incluso con cientos de imágenes.

Manejo de errores

Si la conversión falla para alguna imagen (archivo corrupto, memoria insuficiente, formato inesperado), se conserva el original y el resto del build continúa. Tu documentación no se romperá por un error de conversión de imágenes.

Registros del build

Además del indicador en el dashboard, tus registros del build incluyen una línea como esta:

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