---
title: Imagens Open Graph
description: >-
  Cards sociais 1200×630 gerados para cada página — identidade visual, camadas do card, fontes para escritas não latinas e substituições por página.
---

O Blume pode renderizar um card social de 1200×630 para cada página em tempo de build — sem navegador headless, graças ao [Takumi](https://takumi.kane.tw), então os builds continuam rápidos. Ativado por padrão assim que [`deployment.site`](/pt/docs/deployment) é definido ou detectado automaticamente (a URL de `og:image` precisa ser absoluta para ser útil aos crawlers), e desativado caso contrário ou quando uma [imagem padrão](#default-image) substitui os cards. Defina `enabled` para sobrescrever isso em qualquer direção:

```ts blume.config.ts lineNumbers
seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}
```

## Imagem padrão [#default-image]

Defina `seo.og.image` para compartilhar uma única imagem entre todas as páginas em vez de um card gerado, ou dê a cada locale a sua própria:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    image: { en: "/og/default-en.png", fr: "/og/default-fr.png" },
    // Or image: "https://example.com/og/default.png"
  },
}
```

O `seo.image` de uma página, ou a prop `ogImage` de uma página personalizada, prevalece sobre o padrão. Um locale ausente do mapa usa a imagem do locale padrão. O padrão também cobre páginas personalizadas renderizadas com `PageLayout` e o índice de changelog gerado, então o Blume para de gerar cards assim que ele é definido, a menos que `enabled` seja `true`. Caminhos relativos à raiz são resolvidos sob a base do deploy. O Blume declara as dimensões da imagem apenas para cards gerados. Seja qual for a imagem que uma página acabe usando, ela também vai para o [JSON-LD](/pt/docs/discoverability/structured-data) da página como `image`.

## Aplique sua marca ao card gerado [#brand-the-generated-card]

Defina um SVG local e uma paleta de cores para alinhar o card gerado à sua marca. O logo pode ficar em `public/` ou na raiz do projeto. Omita qualquer valor da paleta para manter o padrão dele.

```ts blume.config.ts lineNumbers
seo: {
  og: {
    logo: "/logo/og.svg",
    palette: {
      accent: "#ff5410",
      background: "#1d1d1d",
      foreground: "#fff6f2",
      muted: "#a6a19f",
      border: "#323232",
    },
  },
}
```

Por padrão, cada card é derivado do seu conteúdo e do seu tema — o **título da página** como manchete, a **descrição da página** como subtítulo (o mesmo texto do seu `og:description`, então `seo.description` prevalece sobre `description`) e o **accent** do seu tema para a marca, que mostra a inicial do **título do site** quando você não definiu um logo. As imagens são servidas em `/og/<slug>.png`, espelhando cada rota, e são pré-renderizadas como arquivos estáticos mesmo no modo servidor:

| Rota da página   | URL da imagem           |
| ---------------- | ----------------------- |
| `/`              | `/og/index.png`         |
| `/quickstart`    | `/og/quickstart.png`    |
| `/guides/deploy` | `/og/guides/deploy.png` |

Sobrescreva o card gerado de qualquer página com `seo.image` — um arquivo em `public/` ou uma URL externa. Ele tem precedência sobre o card gerado e funciona mesmo quando `og` está desativado, então dá para misturar imagens personalizadas com as geradas:

```yaml lineNumbers
---
title: Pricing
seo:
  image: /og/pricing-custom.png
---
```

:::note
Toda cor da paleta aceita qualquer cor CSS — hex, `oklch(…)`, `rgb(…)` e assim por diante. O accent também aceita um preset nomeado (`blue`, `teal`, …), correspondendo a [`theme.accent`](/pt/docs/configuration/theming#accent). Uma cor que o renderizador não consegue interpretar quebra o build em vez de entregar silenciosamente um card com a cor padrão, e uma que nem sequer é uma cor CSS também emite o aviso `BLUME_THEME_COLOR_INVALID` com a linha que a define, antes de o card ser renderizado.
:::

Emojis no título de uma página ou no título do site são renderizados como glifos do [Twemoji](https://github.com/jdecked/twemoji), buscados em uma CDN enquanto o card é renderizado — então um build cujos títulos contenham emojis precisa de acesso à rede. Cada glifo é buscado uma vez por build, não importa quantas páginas o usem.

## Exiba, oculte ou sobrescreva camadas do card [#show-hide-or-override-card-layers]

Além da manchete, o card carrega três camadas opcionais: a **marca** no canto superior esquerdo (seu logo, ou um bloco em accent com a inicial do título do site), o **subtítulo** abaixo da manchete (a `description` da página, ou a `description` do seu site para páginas sem uma) e um **rodapé** com o slug do seu repositório (a partir de `github`) e a URL do site — o host do site de deploy mais [`deployment.base`](/pt/docs/deployment#subpath-deploys), então um site de projeto no GitHub Pages fica `user.github.io/repo`. Sobrescreva qualquer uma delas com uma string sua, ou oculte uma com `false`:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    site: "docs.acme.com", // footer URL text, or false to hide it
    description: false, // hide the subtitle on every card; a string replaces the site fallback
    logo: false, // no brand mark at all — not even the initial tile
  },
}
```

## Fontes do card [#card-fonts]

Por padrão, o card é renderizado com a fonte embutida do Takumi, que cobre apenas glifos latinos básicos — só com ela, um título em outra escrita (japonês, chinês, coreano, árabe, hindi, russo, …) apareceria como tofu, quadradinhos vazios.

**Todas as escritas são cobertas por padrão.** Por trás da fonte embutida, os cards carregam uma pilha de fallback de famílias Google Noto, uma por escrita: `Noto Sans` para cirílico, grego, vietnamita e latim com acentos, depois `Noto Sans JP`, `Noto Sans Arabic`, `Noto Sans Devanagari` e assim por diante. Um título em japonês ou hindi é renderizado sem nada para configurar, mesmo em um site sem [locales](/pt/docs/content/i18n). O fallback é por glifo, então o texto latino mantém a fonte embutida. Um card só busca no Google Fonts quando o texto dele tem um glifo que a fonte embutida não consegue desenhar, e aí só os subconjuntos de que esses glifos precisam: um card em inglês não busca nada, então um site só com escrita latina continua fazendo build offline. A pilha se aplica a menos que `og.fonts` esteja definido, que passa a controlar a lista inteira.

Chinês, japonês e coreano compartilham a maioria dos caracteres Han, mas desenham alguns deles de forma diferente, e os cards usam as formas japonesas por padrão. Cada locale configurado move a própria família para a frente, então um site com um locale `zh` desenha os caracteres Han nas formas do chinês simplificado, e `zh-Hant` ou `zh-TW` nas do tradicional.

**Defina [`theme.fonts`](/pt/docs/configuration/theming#fonts) e o card acompanha.** Quando a sua configuração escolhe as próprias fontes, os cards gerados renderizam automaticamente a manchete na sua fonte de display e a descrição e o rodapé na sua fonte de corpo, então os links compartilhados combinam com o site — incluindo cobertura não latina, sem nada para configurar aqui. (Famílias de provedores que não sejam o Google são ignoradas — o renderizador do card só consegue buscar do Google Fonts —, mas arquivos de fonte locais funcionam.)

Para usar nos cards fontes diferentes das do site, defina `og.fonts` explicitamente. Ele sempre prevalece sobre as fontes derivadas do tema e substitui os fallbacks de escrita, então liste todas as famílias de que seus cards precisam:

```ts blume.config.ts lineNumbers
seo: {
  og: {
    fonts: [
      "Noto Sans JP",
      { name: "Inter", weight: [400, 700] },
      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
    ],
  },
}
```

Cada entrada é um nome de família do Google Fonts, um objeto fixando seu `weight` (um número, uma lista ou um intervalo variável como `"100..900"`) e `style` (`"normal"`, `"italic"` ou ambos), ou um arquivo de fonte local — `src` é resolvido a partir da raiz do projeto, com `weight` e `style` opcionais para quando os metadados do próprio arquivo não devem decidir.

As famílias do Google são buscadas no build — então um build que as usa precisa de acesso à rede — e o renderizador só baixa os subconjuntos de glifos que cada título realmente usa. O fallback é por glifo, então adicionar uma família só afeta os glifos que as outras fontes não conseguem desenhar.

Um `og.fonts: []` explícito desativa tudo: os cards mantêm a fonte embutida mesmo com `theme.fonts` definido ou quando um título precisa de fallback de escrita.

## Cache dos cards [#card-cache]

Os cards renderizados ficam em cache no disco entre builds, indexados por tudo o que define seus pixels: o título e a descrição da página, o texto da marca, o logo, a paleta, o texto do rodapé e as fontes (um arquivo de fonte local pelo seu conteúdo), além da versão do Blume. Um novo build renderiza só os cards cujas entradas mudaram e reaproveita o resto; o log do build informa quantos foram reutilizados. O cache fica em `node_modules/.cache/blume/og`; em uma plataforma que mantém o `node_modules` entre builds (a Vercel e a Netlify mantêm, a Cloudflare não) ou em um runner de CI que faz cache desse diretório (veja [Cache de build](/pt/docs/deployment#build-cache)), um deploy que mexe em meia dúzia de páginas renderiza de novo só meia dúzia de cards. Cards que nenhuma página pediu são removidos após cada build, então o diretório só guarda os cards do site atual.

## Títulos de páginas personalizadas [#custom-page-titles]

Uma [página `.astro`](/pt/docs/advanced/custom-pages) personalizada não tem frontmatter para ler, então o card gerado dela recebe o título humanizando o último segmento da URL da rota — `/getting-started` vira "Getting Started", mas `/cli` vira "Cli". Nomeie esses cards explicitamente com `og.titles`, indexado por rota (`"/"` endereça a home, cujo card, do contrário, carrega o título do site):

```ts blume.config.ts lineNumbers
seo: {
  og: {
    titles: {
      "/cli": "CLI",
    },
  },
}
```

As entradas se aplicam apenas a páginas personalizadas — o card de uma página de conteúdo sempre tira a manchete do título da página, então retitule essas no frontmatter.

`seo.image` é frontmatter, então cobre apenas conteúdo Markdown e MDX. Para dar a uma [página `.astro`](/pt/docs/advanced/custom-pages) personalizada sua própria imagem social — uma home de marketing ou landing page, e a forma de dar só à home uma imagem de compartilhamento sob medida — passe a prop `ogImage` para o `PageLayout`.
