Imagens
Ajuste o tamanho das imagens, adicione legendas, alterne variantes claras e escuras e escolha formatos compatíveis para visuais nítidos e acessíveis.
O Jamdesk exibe imagens com cantos arredondados e espaçamento uniforme. Adicione arquivos ao diretório /images e faça referência a eles usando a sintaxe padrão do Markdown.
As capturas de tela mostram a interface em inglês.
Markdown padrão
Use a sintaxe :


Os caminhos começam na raiz do projeto. Uma imagem em your-docs/images/screenshot.webp é referenciada como /images/screenshot.webp.
Dimensões da imagem
Adicione =WIDTHxHEIGHT após o URL da imagem (separado por um espaço) para controlar o tamanho:

Defina apenas uma dimensão para que a outra seja ajustada proporcionalmente:


Use esse recurso para manter a mesma largura em uma coluna de capturas de tela ou reduzir uma imagem de alta resolução para exibição.
Legendas
Envolva uma imagem com o componente <Frame> para adicionar uma borda e uma legenda abaixo dela:
<Frame caption="Dashboard overview showing project statistics">

</Frame>

Frame funciona com qualquer conteúdo, não apenas com imagens.
Clique para ampliar
Clique em uma imagem para abri-la em tela cheia em telas com 768 px de largura ou mais. Feche a imagem ampliada pressionando Escape ou clicando em qualquer lugar.
Adicione noZoom a uma tag <img loading="lazy"> para impedir a ampliação:
<img src="/_jd/images/diagram.png?v=mwdojjfh" alt="Architecture diagram" data-no-zoom="true" />
Imagens Markdown () não têm sintaxe de atributos. Não é possível desativar a ampliação nelas. Use uma tag <img loading="lazy"> quando precisar de noZoom.
Modo claro/escuro
Os sites de documentação geralmente precisam de variantes de imagem para cada esquema de cores: um logotipo em fundo branco fica estranho no modo escuro.
O atributo srcDark
O Jamdesk troca a origem da imagem para corresponder ao tema ativo:
<img
src="/_jd/images/logo-light.webp?v=mwdojjfh"
srcDark="/images/logo-dark.webp"
alt="Company logo"
/>
O navegador carrega apenas a imagem correspondente ao esquema de cores atual.
O elemento HTML <picture>
Use <picture> com uma consulta de mídia para usar HTML padrão que também funciona fora do Jamdesk:
<picture>
<source srcset="/images/logo-dark.webp" media="(prefers-color-scheme: dark)" />
<img src="/_jd/images/logo-light.webp?v=mwdojjfh" alt="Company logo" />
</picture>
A abordagem com <picture> respeita a configuração de esquema de cores do sistema operacional. Já o atributo srcDark segue a alternância de tema do Jamdesk. Essa geralmente é a opção desejada para sites de documentação.
Formatos compatíveis
| Formato | Ideal para | Observações |
|---|---|---|
| PNG | Capturas de tela, capturas da interface | Qualidade sem perdas, com suporte a transparência. Arquivos maiores. |
| JPEG | Fotografias | Boa compactação, sem suporte a transparência. |
| SVG | Ícones, diagramas, logotipos | Formato vetorial que se ajusta a qualquer tamanho sem perda de qualidade. Arquivos minúsculos. |
| GIF | Animações simples | Os arquivos podem ficar grandes rapidamente. Para animações com mais de alguns quadros, considere loops curtos em .mp4. |
| WebP | Uso geral | Arquivos menores que PNG e JPEG com qualidade comparável. Compatível com todos os navegadores modernos. |
WebP oferece a melhor relação entre tamanho e qualidade para a maioria das imagens de documentação. Também é compatível com transparência. Não é necessário usar PNG para isso.
Boas práticas
Leitores de tela leem o texto alternativo em voz alta. Ele também aparece como texto provisório quando a imagem não carrega. Descreva o que a imagem mostra.
{/* Good -- says what's in the image */}

{/* Bad -- tells you nothing */}
Para imagens decorativas que não acrescentam informações (padrões de fundo, divisórias), use um texto alternativo vazio: .
Imagens pesadas deixam o carregamento das páginas mais lento, especialmente em conexões móveis. Tamanhos recomendados:
- Capturas de tela/interface: PNG ou WebP, menos de 500 KB
- Fotos: JPEG ou WebP, menos de 200 KB
- Ícones e diagramas: SVG sempre que possível
Squoosh e TinyPNG compactam imagens sem perda de qualidade visível. Otimize as capturas de tela com uma dessas ferramentas antes de confirmar as alterações.
O Jamdesk também pode compactar imagens durante o build. Ative a conversão automática para WebP no seu docs.json. Com esse recurso ativado, o Jamdesk otimiza cada arquivo PNG ou JPG confirmado em cada build.
Capturas de tela com larguras diferentes ficam desorganizadas. Escolha uma largura padrão para as capturas (1200 px funciona bem) e use-a em toda a documentação. O Jamdesk ajusta as imagens à área de conteúdo. Dimensões de origem consistentes produzem resultados de exibição consistentes.
O Jamdesk gera um cartão social de marca, com dimensões de 1200×630, para cada página. Substitua-o por página com og:image no frontmatter. Depois de um build, acesse o URL da página na ferramenta gratuita OpenGraph Preview para ver como o cartão aparece no X, Facebook, LinkedIn, Slack, Discord e outros. Consulte Otimização para SEO para ver a configuração completa.
Organização de arquivos
Agrupe imagens em subdiretórios que espelhem a estrutura do seu conteúdo:
your-docs/
├── images/
│ ├── getting-started/
│ │ ├── step-1.png
│ │ └── step-2.png
│ ├── api/
│ │ └── response.png
│ └── logo.svg
└── docs.json
Faça referência a elas usando o caminho completo a partir da raiz do projeto:

Evite espaços nos nomes de arquivos de imagem. Use hífens: api-response.webp, não api response.webp.
