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, 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:

{
  "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

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:

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