Automatic Image Conversion

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. Pages load faster with no 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:

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

That's the only switch. The dashboard Settings page shows the current status under Config Highlights. It has no toggle of its own. docs.json is the source of truth.

What gets converted

Converted images keep their basename and get a .webp extension. Jamdesk rewrites every reference in your MDX, custom CSS, custom JS, and docs.json. 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. A broken preview card is worse than a slightly larger JPG.

Unused images aren't converted either. A file in your /images directory that nothing in your MDX or config references still uploads to the CDN as the original.

Jamdesk keeps the original when the WebP output would be larger than the source file. This is common with already-compressed JPGs and very small PNGs. These show up as skipped in the build stats.

background.image is converted. It's a fullscreen background rendered by the browser.

Build progress indicator

Builds with the feature on show 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. The step doesn't appear when the feature is off.

Build caching

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

Failure handling

Jamdesk keeps the original when conversion fails for an image (corrupt file, out-of-memory, unexpected format). The rest of the build continues.

Build logs

Your build logs include a line like this:

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