Jamdesk Documentation logo

Conversão automática de imagens

Ative a conversão automática de PNG e JPG para WebP no Jamdesk para reduzir o tamanho das imagens e acelerar o carregamento das páginas sem processamento manual.

O Jamdesk pode converter imagens PNG e JPG para o formato WebP durante os builds. Arquivos WebP costumam ter entre 60% e 80% menos tamanho que os originais, sem perda visível de qualidade. As páginas carregam mais rápido, sem nenhum processamento manual de imagens.

O recurso vem desativado por padrão. Ative-o no seu docs.json.

Ative o recurso

Adicione o campo images.convertToWebp ao seu docs.json:

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

Essa é a única opção de ativação. A página de Configurações do painel mostra o status atual em Config Highlights. Ela não tem um botão próprio. O docs.json é a fonte de verdade.

O que é convertido

OrigemConvertido?
PNGSim
JPG / JPEGSim
SVGNão (já é vetorial)
GIFNão (a animação seria perdida)
ICONão (é pequeno demais para fazer diferença)
WebPNão (já está otimizado)

As imagens convertidas mantêm o mesmo nome base e recebem a extensão .webp. O Jamdesk reescreve todas as referências no seu MDX, CSS personalizado, JS personalizado e docs.json. Você não precisa alterar nenhum caminho.

O que permanece original

Algumas imagens não são alteradas, mesmo com a conversão ativada.

Favicons. Nem todos os navegadores ou clientes de e-mail renderizam favicons em WebP de forma confiável.

Imagens de redes sociais (og:image e twitter:image em seo.metatags) também mantêm o formato original. Rastreadores sociais como Facebook, LinkedIn, WhatsApp e o Twitter/X mais antigo nem sempre renderizam WebP. Um cartão de prévia quebrado é pior do que um JPG um pouco maior.

Imagens não utilizadas também não são convertidas. Um arquivo no seu diretório /images que nada no seu MDX ou configuração referencia ainda é enviado ao CDN no formato original.

O Jamdesk mantém o original quando a saída WebP seria maior que o arquivo de origem. Isso é comum com JPGs já comprimidos e PNGs muito pequenos. Esses casos aparecem como skipped nas estatísticas do build.

background.image é convertido. É um plano de fundo em tela cheia renderizado pelo navegador.

Indicador de progresso do build

Builds com o recurso ativado mostram a etapa Otimizando imagens na lista de progresso do painel, entre "Construindo documentação" e "Enviando para o CDN". A CLI jamdesk deploy mostra a mesma etapa na saída de progresso do terminal. A etapa não aparece quando o recurso está desativado.

Cache do build

O Jamdesk armazena um hash de cada imagem de origem no manifesto do build. Ele pula a conversão de um arquivo que não mudou desde o último build e reutiliza o WebP em cache. Os rebuilds continuam rápidos, mesmo com centenas de imagens.

Tratamento de falhas

O Jamdesk mantém o original quando a conversão falha para uma imagem (arquivo corrompido, falta de memória, formato inesperado). O restante do build continua.

Logs do build

Os logs de build incluem uma linha como esta:

Optimizing images... done (4 converted, 2 cached, 1 skipped, 0 failed, saved 1.2 MB)
CampoSignificado
convertedImagens convertidas de PNG/JPG para WebP neste build
cachedImagens inalteradas, mantidas do build anterior
skippedImagens mantidas como originais (campos protegidos, arquivos não utilizados ou formatos que não precisam de conversão)
failedConversões que falharam (originais mantidos)
savedTotal de bytes economizados nas imagens convertidas