Jamdesk Documentation logo

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 ![alt](path):

![API response showing user data in JSON format](/images/tabs-preview.webp)

Resposta da API mostrando dados do usuário em formato JSON

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:

![Dashboard overview](/images/tabs-preview.webp =400x300)

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

![Wide banner](/images/tabs-preview.webp =800x)
![Tall graphic](/images/tabs-preview.webp =x200)

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

  ![Dashboard](/images/tabs-preview.webp)

</Frame>

Jamdesk

Exemplo de imagem emoldurada com legenda

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 (![alt](src)) 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

FormatoIdeal paraObservações
PNGCapturas de tela, capturas da interfaceQualidade sem perdas, com suporte a transparência. Arquivos maiores.
JPEGFotografiasBoa compactação, sem suporte a transparência.
SVGÍcones, diagramas, logotiposFormato vetorial que se ajusta a qualquer tamanho sem perda de qualidade. Arquivos minúsculos.
GIFAnimações simplesOs arquivos podem ficar grandes rapidamente. Para animações com mais de alguns quadros, considere loops curtos em .mp4.
WebPUso geralArquivos 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 */}
![API response showing user data in JSON format](/images/tabs-preview.webp)

{/* Bad -- tells you nothing */}
![Screenshot](/images/tabs-preview.webp)

Para imagens decorativas que não acrescentam informações (padrões de fundo, divisórias), use um texto alternativo vazio: ![](/_jd/images/decoration.webp?v=mwdojjfh).

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:

![GitHub repository access](/images/getting-started/step-1.png)

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

Próximos passos

Incorporações do YouTube

Incorpore vídeos e Shorts do YouTube

Vídeos

Arquivos MP4 e WebM locais

iFrames

Vimeo, CodePen, Figma e muito mais