Metadados de imagem OpenGraph no gerador de sites estáticos Hugo

Como adicionar metadados OpenGraph ao Hugo?

Conteúdo da página

Metadados da imagem Opengraph é a propriedade meta og:image. Basicamente, queremos gerar corretamente a tag <meta property="og:image" content="https://....jpg"> para cada página no nosso site baseado em Hugo.

Logotipo e slogan do Hugo

Como incluir metadados OpenGraph

Pesquise no código do seu tema por:

{{ template "_internal/opengraph.html" . }}

Provavelmente já está incluído. Se não o encontrar em nenhum lugar, você pode tentar incluí-lo manualmente:

  • Crie ou copie o arquivo layouts/_default/baseof.html do seu tema
  • Adicione em algum lugar dentro da tag <head>:
<head>
  .....
  {{ template "_internal/opengraph.html" . }}

Pronto? Agora gere seu site com o comando hugo e verifique o index.html produzido para alguma página.

hugo
head -100 public/post/test/index.html

Você não vê o <meta property="og:image"... ali, correto?

Ok… existem mais algumas condições na implementação padrão.

Documentação oficial do Hugo

https://gohugo.io/templates/embedded/#open-graph

  1. Basicamente, você precisa especificar no frontmatter da página as imagens que deseja publicar nos metadados, por exemplo:
---
title: "Título da minha página de teste Hugo"
description: "Descrição da minha página de teste Hugo"

date: "2025-07-15"
lastmod: "2025-07-15"

tags:
  - Hugo
  - Imagens

images:
  - post-cover1.png
  - post-cover2.png
---

Mas isso pode ser tarde demais, pois você já pode ter um site com milhares de páginas. Não se preocupe, existe outra opção.

  1. Armazene imagens em seu pacote de página (page bundle) com nomes especiais.

Aquele _internal/opengraph.html chama _funcs/get-page-images.html, que procura no seu pacote de página por arquivos de imagem que contenham feature (como feature.png); em seguida, se a imagem de destaque não for encontrada, procura por arquivos de imagem com nomes contendo cover ou thumbnail.

Parte do get-page-images.html:

{{- $featured := $resources.GetMatch "*feature*" -}}
  {{- if not $featured }}{{ $featured = $resources.GetMatch "{*cover*,*thumbnail*}" }}{{ end -}}
  {{- with $featured }}
    {{- $imgs = $imgs | append (dict
      "Image" .
      "RelPermalink" .RelPermalink
      "Permalink" .Permalink) }}
  {{- end }}
  1. Fallback para parâmetros globais do site – pegará apenas a primeira imagem.

Em algum lugar no hugo.toml:

[params]
  description = 'Meu site incrível'
  images = ['default-feature-image.jpg']

ou no hugo.yaml, caso você use isso:

params:
  description: Meu site incrível'
  images:
  - default-feature-image.jpg

Você pode encontrar esse código ali, no get-page-images.html:

{{- if and (not $imgParams) (not $imgs) }}
  {{- with site.Params.images }}
    {{- $imgParams = first 1 . }}
  {{- end }}
{{- end }}

Este site

Como você deve ter adivinhado e pode ver, este site também utiliza Hugo. Aqui, tenho imagens de miniatura referenciadas no frontmatter da página da maneira padrão do Hugo/MainRoad:

thumbnail: this-page-thumbnail.jpg

Mas minhas miniaturas já foram redimensionadas para uma largura de 235px… Ops… isso não é suficiente para a imagem de capa da página. E outras imagens têm todos os nomes diferentes…

Fiz a correção da maneira fácil – apenas coloquei no config do site os parâmetros de imagem padrão. E agora todas as páginas anteriores a este post têm a imagem deste pequeno cluster Kubernetes como seu metadado opengraph:

empilhamento usff dell

Posso mudar algo no futuro, tipo escrever algum script automático para atualizar todas as seções de frontmatter das páginas, mas por enquanto é suficiente.

Assinar

Receba novos artigos sobre sistemas, infraestrutura e engenharia de IA.