Imagens Open Graph

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, então os builds continuam rápidos. Ativado por padrão assim que deployment.site é 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 substitui os cards. Defina enabled para sobrescrever isso em qualquer direção:

seo: {
  og: { enabled: true }, // or false to opt out even with a site set
}

Imagem padrão

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:

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 da página como image.

Aplique sua marca ao card gerado

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.

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:

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:

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

Emojis no título de uma página ou no título do site são renderizados como glifos do 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

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, 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:

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

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. 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 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:

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

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), 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

Uma página .astro 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):

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