Metadados de imagem OpenGraph no gerador de site estático Hugo

Como adicionar metadados opengraph ao hugo?

Conteúdo da página

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

Logotipo e slogan do Hugo

Como os metadados OpenGraph são incluídos

Procure no código do seu tema por

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

Provavelmente ele já está incluindo. Se não for encontrado em lugar algum, você pode tentar incluí-lo manualmente

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

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

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

Você não vê a tag <meta property="og:image"... lá, certo?

Okay… existem algumas condições adicionais na implementação padrão.

Documentação oficial do Hugo

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

  1. Basicamente, você precisa especificar nas metadados da página as imagens que deseja que sejam publicadas nos metadados, por exemplo
---
title: "Meu título de teste do Hugo"
description: "Descrição da minha página de teste do 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, já que você já tem um site com milhares de páginas. Não se preocupe, existe outra opção.

  1. Armazene as imagens no seu pacote de página com nomes especiais.

Essa _internal/opengraph.html chama _funcs/get-page-images.html que procura nos arquivos de imagem do seu pacote de página por arquivos que contenham feature (como feature.png), depois, se a imagem destacada não for encontrada, procura por imagens com nomes que contenham 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 incrível site'
  images = ['default-feature-image.jpg']

ou no hugo.yaml, caso você use esse formato

params:
  description: Meu incrível site'
  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

Este site, como você já adivinhou e pode ver, também está usando Hugo. Aqui, tenho imagens de miniatura referenciadas na seção de metadados da página da forma padrão do Hugo/MainRoad:

thumbnail: this-page-thumbnail.jpg

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

Corrigi de forma fácil - apenas coloquei os parâmetros de imagem padrão na configuração do site. E agora todas as páginas antes deste post têm a imagem desse pequeno cluster do Kubernetes como seu metadado opengraph:

dell usff stack

Talvez eu mude algo no futuro, algo como escrever um script automático para atualizar todas as seções de metadados das páginas, mas por enquanto é suficiente.