---
title: Automatic Image Conversion
description: Convert PNG and JPG images to WebP during builds for smaller file sizes and faster page loads.
---

Jamdesk can convert PNG and JPG images to WebP format during builds. WebP files are usually 60-80% smaller than the originals with no visible quality loss, so your pages load faster without any manual image processing.

The feature is **off by default**. Turn it on in your `docs.json`.

## Enable it

Add the `images.convertToWebp` field to your `docs.json`:

```json docs.json
{
  "images": {
    "convertToWebp": true
  }
}
```

That's the only switch. The Settings page in the dashboard shows the current status under **Config Highlights**, but it doesn't have its own toggle. `docs.json` is the source of truth.

## What gets converted

| Source | Converted? |
|--------|------------|
| PNG | Yes |
| JPG / JPEG | Yes |
| SVG | No (already vector) |
| GIF | No (animation would be lost) |
| ICO | No (too small to matter) |
| WebP | No (already optimized) |

Converted images keep their basename and get a `.webp` extension. Every reference in your MDX, custom CSS, custom JS, and `docs.json` is rewritten automatically. You don't change any paths.

## What stays as originals

Some images are left untouched even when conversion is on.

**Favicons.** Not every browser or email client renders WebP favicons reliably.

Social media images (`og:image` and `twitter:image` in your `seo.metatags`) also stay in their original format. Social crawlers like Facebook, LinkedIn, WhatsApp, and older Twitter/X don't all render WebP, and a broken preview card is worse than a slightly larger JPG.

Unused images get a pass too. If a file sits in your `/images` directory but nothing in your MDX or config references it, the original still uploads to the CDN, but it isn't converted. No sense spending CPU on something nothing links to.

Images that wouldn't benefit from conversion stay as originals. If the WebP output would be larger than the source file (common with already-compressed JPGs and very small PNGs), Jamdesk keeps the original. These show up as `skipped` in the build stats.

One thing that *is* converted: `background.image`. It's a fullscreen background rendered by the browser, so it benefits from WebP like any other image.

## Build progress indicator

When the feature is on, your build shows an **Optimizing images** step in the dashboard progress list, between "Building documentation" and "Uploading to CDN". The `jamdesk deploy` CLI shows the same step in its terminal progress output. When the feature is off, the step doesn't appear at all.

## Build caching

Jamdesk stores a hash of each source image in the build manifest. If a file hasn't changed since the last build, it skips the conversion and reuses the cached WebP. Rebuild times stay fast even with hundreds of images.

## Failure handling

If conversion fails for any single image (corrupt file, out-of-memory, unexpected format), the original is kept and the rest of the build continues. Your docs won't break because of an image conversion error.

## Build logs

Alongside the dashboard indicator, your build logs include a line like this:

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

| Field | Meaning |
|-------|---------|
| converted | Images converted from PNG/JPG to WebP this build |
| cached | Unchanged images carried forward from the previous build |
| skipped | Images left as originals (protected fields, unused files, or formats that don't need conversion) |
| failed | Conversions that failed (originals kept) |
| saved | Total bytes shaved across all converted images |