Guia 3: adicionar imagens a artigos e Fragments
Coloque os originais, use os caminhos corretos e prepare arquivos responsivos, capas e prévias de compartilhamento.
Nesta página
Esta é a parte 3 de 8 do guia inicial. Veja a ordem completa · Consulte a referência por campo.
Você não precisa criar várias resoluções manualmente nem trocar os links dos artigos pelos nomes gerados. Coloque o original, referencie-o no artigo ou Fragment e deixe o servidor local preparar os arquivos responsivos necessários.
Este guia considera os diretórios padrão src/ e public/ do starter. Primeiro identifique o uso da imagem:
| Uso | Onde configurar | Processamento atual |
|---|---|---|
| Imagem no corpo do artigo | Imagem Markdown ou dentro de MDX | Usa o fluxo Markdown/MDX existente, fora da preparação persistente de capas descrita abaixo. |
| Capa de artigo | heroImage no frontmatter |
Arquivos responsivos preparados localmente, compartilhados pela lista e pelo artigo. |
| Imagem de Fragment | Imagem Markdown, por referência ou HTML img no corpo |
Imagens locais suportadas usam os mesmos arquivos persistentes, na lista e na prévia inicial. |
| Imagem de compartilhamento | ogImage do artigo ou site.ogImage |
Fluxo próprio, distinto das miniaturas de capa. |
1. Colocar o original no projeto
Uma imagem usada em um único artigo pode ficar ao lado dele:
src/content/blog/zh/
my-first-post.md
photo.jpg
cover.jpg
Fragments aceitam a mesma organização, com imagens ao lado do Markdown. Imagens compartilhadas entre páginas podem ficar em public/images/:
public/images/
shared-photo.jpg
fragments/
my-photo.png
Crie os diretórios se não existirem. Prefira nomes simples com letras inglesas, números e hífens, evitando confusão de maiúsculas e minúsculas. URLs usam /, não caminhos locais como C:\..., D:\... ou barras invertidas. Em sistemas que distinguem maiúsculas, Photo.jpg e photo.jpg podem ser arquivos diferentes.
Mantenha o original. O WebP gerado para exibição é um derivado, não um backup substituto.
2. Inserir imagens no corpo de um artigo
Abra o Markdown do artigo e insira no local desejado:

./photo.jpg é relativo ao arquivo do artigo. Na organização acima, aponta para photo.jpg na mesma pasta. Para arquivos de public:

Esse caminho corresponde a public/images/shared-photo.jpg e omite public na URL. O texto entre colchetes é a descrição alternativa: descreva o conteúdo real, em vez de escrever apenas “imagem”.
Imagens comuns do corpo podem ser ampliadas por clique ou por foco seguido de Enter/espaço. Esc, o botão de fechar ou a máscara fecham a prévia. Capas e imagens dentro de links ou botões ficam de fora. A ampliação usa a fonte já escolhida pelo navegador, sem baixar automaticamente um original de maior resolução e sem navegação entre imagens.
Executar prepare-covers não significa que todas as imagens do corpo foram comprimidas. Ele processa os conjuntos de capas, as capas referenciadas e as imagens locais de Fragments. Imagens public no corpo de artigos ainda podem baixar o original diretamente. Prepare arquivos de tamanho adequado, especialmente evitando screenshots de vários MB.
3. Definir a capa do artigo
Coloque cover.jpg ao lado do artigo e adicione ou altere no frontmatter existente:
heroImage: ./cover.jpg
heroImage é opcional, mas, quando usado, deve apontar para um arquivo local do projeto, não uma URL HTTPS direta. Não use /images/cover.jpg como se esse campo tivesse a mesma regra de URLs public das imagens no corpo.
Para centralizar novas capas, use src/assets/blog/covers/originals/. Se o artigo está em src/content/blog/zh/my-first-post.md e o original em src/assets/blog/covers/originals/my-cover.jpg, escreva:
heroImage: ../../../assets/blog/covers/originals/my-cover.jpg
A capa não é inserida automaticamente no corpo. Ela aparece nas listas do blog/tags e na área de capa do artigo. O layout pode recortar a área visível, mas os arquivos gerados preservam a proporção original; não escolhem automaticamente uma pessoa ou o foco da composição.
A seleção automática de new-post usa apenas src/assets/blog/default-covers/. Colocar uma imagem em covers/originals/ não a inclui nessa seleção: referencie o novo original no artigo.
4. Adicionar imagens a Fragments
Com theme.fragments.enabled: false, dev, build e prepare-covers/doctor ignoram referências de imagens no corpo dos Fragments. Imagens incluídas somente por essas referências deixam de exigir originais ou derivados. Referências de capas e os conjuntos src/assets/blog/default-covers/ e src/assets/blog/covers/originals/ continuam preparados e validados, mesmo para imagens usadas só em Fragments. Nenhum arquivo é apagado; reativar restaura o processamento de Fragments.
Nota de versão: O isolamento de imagens ao desativar exige 0.36.1 ou posterior; não está em 0.36.0. Não presuma esse comportamento em versões antigas.
Coloque o original em public/images/fragments/my-photo.png e escreva no corpo do Fragment existente:

Você também pode colocar photo.png junto do Fragment e usar . Apenas copiar uma imagem para public não inicia uma varredura geral de biblioteca: ela precisa ser referenciada em um Fragment real.
Imagens por referência também funcionam:
![Descrição da imagem][photo]
[photo]: /images/fragments/my-photo.png
Para tamanhos manuais, use HTML:
<img src="/images/fragments/my-photo.png" alt="Descrição da imagem" width="640" height="360" />
As dimensões são exemplos; preencha valores de acordo com a proporção real. Imagens locais suportadas recebem dimensões ausentes automaticamente. Dimensões já preenchidas são mantidas; se houver apenas uma, a outra é calculada pela proporção original. Valores existentes incorretos não são corrigidos.
A primeira imagem de cada página da lista de Fragments tem prioridade de carregamento; as outras e as miniaturas iniciais são lazy. A página inicial mostra apenas uma prévia com altura limitada e recorta o excesso. Não é um visualizador completo: clique no card para abrir o Fragment original. Criação, ID estável e comentários estão em publicar um Fragment.
5. Preparar os arquivos responsivos localmente
Depois de referenciar ou trocar um original, inicie o servidor local na raiz do projeto:
npm run dev
Dev, build e doctor, inclusive em CI, reutilizam derivados válidos e preparam os ausentes, desatualizados ou danificados. Dev também acompanha alterações nas fontes e referências. Se quiser apenas preparar imagens sem iniciar páginas nem a verificação completa, pare dev e execute:
npx @anglefeint/astro-theme prepare-covers
Para conferir os arquivos atuais sem gerar o que estiver faltando:
npx @anglefeint/astro-theme prepare-covers --check
Não é necessário recodificar tudo a cada execução. A preparação usa hashes do original, das regras e dos arquivos de saída para decidir o que reutilizar. Um original alterado atualiza seus derivados; uma única saída ausente ou modificada exige reparar apenas a parte necessária. Não edite o manifesto, renomeie saídas ou grave suas URLs geradas no artigo.
As regras atuais são:
- Imagens raster estáticas viram WebP com qualidade 80: é um objetivo de codificação com perdas, não uma garantia de pixels idênticos.
- As larguras candidatas são 400, 640, 800, 960 e 1200px. Mantêm-se as adequadas ao original e, se necessário, sua largura até 1200px, sem ampliar imagens pequenas.
- A orientação EXIF é aplicada e a proporção é preservada, sem criar recortes com composições diferentes.
- SVG e animações com vários quadros mantêm o formato; não viram WebP estático. GIF de um quadro pode ser processado como imagem estática: a extensão sozinha não determina a preservação.
- Os conjuntos default-covers, originals e as referências reais definem o alcance. Nem todas as imagens de public são convertidas.
O navegador escolhe a candidata por srcset, sizes, tela e densidade de pixels. Você não precisa manter diretórios de vários tamanhos. Como a maior largura é 1200px, não se garante detalhe equivalente ao original em telas grandes com alta densidade.
6. O que versionar e o que acontece na publicação?
Depois da preparação, os arquivos ficam em:
src/assets/blog/covers/
originals/ # se você usar este diretório de originais
manifest.json # origens, dimensões, regras e hashes de saída
generated/ # arquivos responsivos persistentes
Faça commit em conjunto de:
- Markdown do artigo ou Fragment e dos originais adicionados ou substituídos.
- Todo
src/assets/blog/covers/, incluindo manifesto e arquivos gerados.
Se o original estiver em public ou junto do artigo, inclua também esse arquivo, não apenas originals. Mesmo com o nome blog/covers, o diretório também guarda os derivados de Fragments.
Antes de publicar, pare dev e execute npm run doctor localmente; após o sucesso, npm run preview mostra o build. doctor já constrói, sem necessidade de build imediato adicional. A hospedagem continua usando npm run build e dist, publicando todos os arquivos de saída.
Dev, build e doctor, inclusive em CI, preparam automaticamente os derivados utilizados: reutilizam os válidos e geram os ausentes, desatualizados ou danificados. Guardar os derivados no Git permite reutilizá-los sem depender do cache da plataforma. Originais ausentes, ilegíveis ou fora dos caminhos permitidos continuam causando erros.
Requer 0.36.2 ou posterior: Dev, build e doctor (inclusive em CI) reutilizam derivados válidos e geram os ausentes, desatualizados ou danificados. Na versão 0.36.1, prepare as imagens primeiro com dev ou prepare-covers antes de build/CI. prepare-covers --check e a sincronização da configuração continuam sendo verificações somente de leitura.
Derivados usados no build são copiados para _blog-covers/. Não publique só HTML nem deixe esse diretório de fora. Arquivos antigos ou sem uso em generated não são apagados automaticamente. Antes de limpar, confira as referências e não apague originais ainda necessários.
Consulte os campos em heroImage e ogImage de artigos e as regras de prévia de Fragments.
7. Qual imagem aparece ao compartilhar um link?
A imagem de compartilhamento é a prévia do cartão do link, diferente da capa exibida na página.
Por padrão, o build gera para cada artigo um PNG 1200×630 com título, autor e nome do site, sem serviço de imagens nem geração no navegador. Ao mudar essas informações, reconstrua e publique. theme.footer.showCredits também controla o crédito do tema nessa imagem automática, sem alterar imagens próprias.
Escolher uma imagem para um artigo
Coloque share.png ao lado do artigo e preencha no frontmatter:
ogImage: ./share.png
Ou coloque o arquivo em public/images/share.png e use ogImage: /images/share.png. O campo também aceita URL HTTPS direta. Imagens locais relativas são tratadas pelo schema de imagens do artigo; caminhos public têm sua existência verificada. Links externos dependem do servidor de origem.
Definir uma imagem padrão para páginas sem imagem própria
Mescle no site de nível superior existente em src/site.config.ts:
site: {
ogImage: '/images/site-share.jpg',
},
Coloque primeiro o arquivo em public/images/site-share.jpg. site.ogImage também aceita HTTPS. Ausente ou vazio, usa a imagem 1200×630 interna do tema. Não aceita caminhos relativos ao artigo.
A prioridade atual é:
ogImageexplícito do artigo.- Imagem automática do artigo, com geração habilitada.
heroImagedo artigo quandotheme.socialImage.enabledestá desabilitado.site.ogImagepara páginas sem imagem específica e, por último, a imagem interna.
Assim, alterar apenas site.ogImage não substitui as imagens automáticas dos artigos. A página Fragments e todos os links #ID compartilham a imagem padrão do site, sem um cartão específico para cada item.
As imagens automáticas ficam em dist/_social/. Plataformas leem os metadados do site publicado e podem manter imagens antigas em cache; uma imagem local nova não significa atualização imediata da prévia externa.
8. Como investigar problemas de imagens
| Sintoma | O que conferir primeiro |
|---|---|
| Imagem não aparece | Existência do arquivo, maiúsculas/minúsculas e caminho relativo ao Markdown atual; URLs public não levam public. |
| Preparação da capa falha | heroImage precisa apontar para arquivo local do projeto, sem confundir com URL externa ou public; veja o erro completo no terminal. |
| Aviso missing/stale/modified derivatives | Execute dev, build ou doctor para regenerar os derivados; use prepare-covers para preparação explícita. Confira os originais se persistir. |
| Imagem em public sem tamanhos gerados | Verifique se um Fragment a referencia; imagens public comuns do corpo de artigos ficam fora dessa varredura. |
| GIF ou SVG continua grande | Animações e vetores preservam o original; o comando não converte para vídeo nem comprime animações. |
| Imagem remota de Fragment lenta ou com saltos | Links externos não são convertidos nem têm dimensões inferidas; otimize na origem e preencha largura e altura corretas. |
| Imagem local funciona, publicada não | Versione os originais; os derivados podem ser regenerados. Publique todo dist e confira reescritas de caminhos. |
| Prévia de compartilhamento antiga | Verifique novo build/publicação, prioridade da imagem do artigo e cache da plataforma. |
Se personalizar srcDir, publicDir ou fontes com base no Astro, prepare usando dev com essas configurações. O comando prepare-covers independente usa os diretórios padrão. Suporte parcial a base no processamento de imagens não equivale a suporte integral a qualquer subdiretório de publicação.
Para instalar ou atualizar, consulte instalar o blog e colocar suas informações; campos e corpo dos artigos estão em escrever o primeiro artigo.
Navegação e referência de configuração
Anterior: escrever o primeiro artigo · Próximo: publicar um Fragment · Índice dos oito guias.
Campos relacionados: capas e compartilhamento de artigos, imagens na prévia de Fragments e imagem padrão do site. Consulte caminhos completos, valores padrão e limites no índice da referência.