Deep Dive: Hugo – o que um gerador de sites estáticos faz, o que substituiu meus plugins do WordPress e como a busca funciona sem servidor

O que é o Hugo e como ele difere do WordPress, o que assumiu as tarefas do Yoast, do Polylang e dos plugins de cache, como uma caixa de busca funciona num site sem servidor, como eu adiciono um post e atualizo o Hugo – e quais armadilhas só apareceram na operação.

Um pequeno robô numa esteira transforma páginas Markdown em páginas HTML prontas e cola etiquetas de SEO nelas, o monitor mostra Markdown → Hugo → HTML

🌐 Também em: English · Deutsch · Français · Español · Italiano · Nederlands · Polski

Deep Dive da série em torno do Ansible Tour. O tour explica as roles; os deep dives, a tecnologia por baixo: como ela funciona, por que é usada desse jeito aqui e o que deu errado pelo caminho.

No início de novembro este blog saiu do WordPress no Kubernetes e foi para o Hugo. O experimento com números reais e a mudança em si são contados em outro lugar. Este post é a visão geral que eu gostaria de ter tido antes de começar: o que o Hugo realmente é, o que assumiu as tarefas dos plugins do WordPress, como uma caixa de busca funciona num site que não tem nenhum código no servidor, o que eu faço quando adiciono um post ou atualizo o Hugo, e onde ele me surpreendeu.

Índice

🧭 O que é o Hugo

Uma gráfica em vez de uma cozinha

O WordPress funciona como a cozinha de um restaurante: toda vez que um cliente faz um pedido, o PHP cozinha a página a partir do banco de dados – a não ser que um plugin de cache já tenha um prato pronto. O Hugo funciona como uma gráfica: ele imprime cada página uma vez, com antecedência, e o servidor web só entrega cópias prontas. Nada é cozinhado quando um leitor chega.

Tecnicamente, o Hugo é um static site generator: um único programa escrito em Go que lê arquivos Markdown, templates e imagens e escreve uma pasta cheia de HTML, CSS, imagens e feeds. Essa pasta é o site. Qualquer servidor web consegue entregá-la; aqui é um nginx simples.

Um binário, duas edições

O Hugo é um executável sem dependências – sem PHP, sem banco de dados, sem Node.js. Ele vem numa edição padrão e numa extended; a extended adiciona codificação WebP e Sass. Este blog usa a edição extended, versão 0.169.0, porque toda imagem é redimensionada e convertida para WebP durante o build.

A lição: o Hugo move todo o trabalho do momento da visita para o momento da publicação. Todo o resto deste post vem daí.

⚖️ Hugo versus WordPress

PerguntaWordPressHugo
Quando uma página é feita?A cada requisição (ou do cache)Uma vez, no build
O que roda no servidor?PHP, MariaDB, muitas vezes RedisSó o servidor web
Superfície de ataqueLogin, admin, plugins, XML-RPC, PHPArquivos estáticos
Atualizações regularesCore, plugins, temas, PHPnginx; Hugo só na máquina de build
Onde eu escrevo?Editor no navegadorEditor de texto, Git
Comentários, formuláriosEmbutidosPrecisam de um serviço externo
VelocidadeCom cache: 58 ms para a página inicial57 ms – nenhuma diferença
Peso da página (inicial, sem imagens)25 arquivos, 198 KB3 arquivos, 9,5 KB

Os números vêm das minhas próprias medições antes da mudança. A velocidade não foi o motivo: um WordPress com bom cache é tão rápido quanto. Os motivos foram o resto da tabela – nenhum login para atacar, nenhuma atualização de plugin toda semana, nenhum banco de dados para fazer backup, e uma página 95 % menor.

Do que eu abri mão: o editor no navegador, os comentários e o conforto de instalar uma funcionalidade com um clique.

A lição: o WordPress é um programa que produz um site. O Hugo produz o site uma vez e sai do caminho. Se isso é melhor depende de você precisar ou não do que só o programa em execução consegue fazer.

🔧 Como o Hugo funciona

Conteúdo: Markdown com front matter

Cada post é um arquivo Markdown. No topo fica o front matter, um bloco de YAML que o Hugo lê como dados. Um post deste blog começa assim:

---
title: 'Zabbix in Containers Watches My Home Network'
slug: zabbix-in-containers-watches-my-home-network
date: '2026-11-13T15:40:00+01:00'
translationKey: zabbix-heimnetz-2026-11
description: 'Short summary for search results, at most about 155 characters.'
categories:
- linux
tags:
- zabbix
image: uploads/2026/11/zabbix-watchman.webp
imageAlt: What the picture shows, for screen readers and search engines
---

Abaixo do segundo --- vem o texto. O Markdown cobre títulos, listas, tabelas e código; onde ele não basta, HTML cru é permitido (unsafe = true nas configurações do Goldmark), o que importa para os posts convertidos do WordPress.

Pastas, seções e endereços

site/
├── content/en/posts/   posts in English (one folder per language)
├── content/de/posts/   posts in German, and so on for eight languages
├── layouts/            templates: the theme
├── assets/             CSS and JavaScript, processed by Hugo
├── uploads/            images and downloads
├── i18n/               interface words per language ("Read more", "Search")
├── data/               menus, flags, footer text as JSON
└── hugo.toml           configuration

O hugo.toml decide os endereços: posts = "/:year/:month/:day/:slug/" mantém o esquema de URL que o WordPress usava, então nenhum link antigo quebrou. Categorias e tags são taxonomies; o Hugo cria sozinho uma página para cada categoria e cada tag.

Templates

Os templates usam a linguagem de templates do Go. baseof.html é a moldura de toda página, page.html um post individual, home.html a página inicial, e os partials são peças reutilizáveis – o cabeçalho, a sidebar, o <head> com todas as meta tags. Não uso nenhum tema pronto: os layouts foram escritos para ficar parecidos com o antigo tema do WordPress.

O pipeline de assets

O Hugo processa os arquivos ele mesmo: resources.Get "css/main.css" | minify | fingerprint minifica a folha de estilo e coloca um hash no nome do arquivo, para que os navegadores possam guardá-la em cache para sempre. As imagens são redimensionadas durante o build – a imagem de prévia para redes sociais, por exemplo, é criada a partir da imagem do post em 1200 px e reduzida até ficar abaixo de 280 KB, o limite para prévias no WhatsApp.

Multilíngue desde o início

Cada idioma tem sua própria pasta de conteúdo, rótulo e locale no hugo.toml. Posts que pertencem um ao outro compartilham uma translationKey; a partir dela o Hugo conhece as traduções de cada página e monta o seletor de idioma e os links hreflang. Este blog agora tem oito idiomas – inglês, alemão, francês, espanhol, italiano, português, holandês e polonês.

Prévia e rascunhos

hugo server monta o site na memória e o serve em localhost:1313; cada arquivo salvo recarrega o navegador. draft: true deixa um post fora do build de verdade, e uma data no futuro também – falo mais sobre isso abaixo.

A lição: conteúdo, templates e configuração são três tipos separados de arquivo. Você pode mudar o visual sem mexer em um único post, e escrever um post sem saber como os templates funcionam.

🧩 Para onde foram os plugins

No WordPress, quase toda funcionalidade era um plugin. No Hugo, uma funcionalidade ou é embutida, ou são algumas linhas de template, ou um pequeno script que roda depois do build.

Plugin do WordPressTarefaAgora
Yoast SEOTítulo, description, canonical, Open Graph, dados estruturadoshead.html (um template para todas as páginas)
Yoast SEOSitemapEmbutido no Hugo, template sitemap.xml próprio com hreflang
Yoast SEO“Seu post não tem description”check_posts.py: o build para
PolylangIdiomas, seletor de idiomaEmbutido no Hugo
CompressXImagens WebP, tamanhos menoresProcessamento de imagens do Hugo
AutoptimizeMinificar CSS, JS, HTMLhugo --minify
WP Super Cache, RedisCache de página e de objetosDesnecessário – toda página já é um arquivo
Busca (WordPress)Busca full-textPagefind (próxima seção)

SEO sem plugin

O Yoast fazia três coisas: escrevia meta tags, montava um sitemap e ficava enchendo o saco. As duas primeiras agora são um único partial, head.html. Para cada página ele escreve o título (ou um seoTitle mais curto do front matter), a description, um link canonical, um link hreflang por tradução, as tags Open Graph e Twitter com uma imagem de prévia gerada, as datas do artigo e um bloco JSON-LD com os mesmos dados estruturados que o Yoast produzia (Article, WebPage, BreadcrumbList, Person). É um arquivo só, e é igual para todas as páginas – nenhuma tela de configuração por post.

A chatice foi para dentro do build: tools/check_posts.py para o build se um post não tem título, description, imagem, texto da imagem, chave de tradução ou data, ou se o arquivo da imagem não existe, e avisa quando uma description fica longa demais ou falta uma tradução.

Extensões no Hugo

O Hugo não tem loja de plugins, mas tem pontos de extensão:

  • Temas e Hugo Modules – visuais completos ou partes de um, puxados como uma dependência. Este blog monta suas próprias pastas via module.mounts (a pasta de uploads é montada duas vezes: uma para o processamento de imagens, outra como /wp-content/uploads/ para que os endereços antigos das imagens continuem funcionando).
  • Shortcodes – pequenos templates que você chama a partir do Markdown, por exemplo para um vídeo ou uma caixa de aviso.
  • Render hooks – seu próprio template para cada link, imagem ou título que o Markdown gera.
  • Formatos de saída – o mesmo conteúdo como HTML, RSS, JSON ou qualquer outra coisa.
  • Ferramentas depois do build – o build é só uma pasta, então qualquer programa pode trabalhar nela. Aqui, imgattrs.py adiciona srcset e lazy loading às imagens dentro de posts antigos, e o Pagefind monta o índice de busca.

A lição: a maioria dos plugins resolvia problemas que um site estático não tem. O resto virou um template ou um script que eu consigo ler inteiro – o que também significa que ninguém mais os atualiza por mim.

🔍 Como a busca funciona sem servidor

Uma caixa de busca parece precisar de um servidor: alguém tem que procurar as palavras. O Pagefind leva esse trabalho também para o build.

  1. No build, o Pagefind lê cada página HTML pronta. Ele só indexa a parte marcada com data-pagefind-body (o artigo), então menus e sidebars não poluem os resultados, e pula tudo que estiver marcado com data-pagefind-ignore. Ele detecta o idioma pelo atributo lang e monta um índice por idioma.
  2. O índice é dividido em muitos arquivos pequenos em /pagefind/ – 18 MB no total para oito idiomas. Ninguém baixa tudo.
  3. No navegador, nada é carregado até alguém realmente buscar. Aí algumas linhas de JavaScript importam o Pagefind, que busca só os pedaços do índice para as palavras digitadas e os fragmentos das páginas encontradas, e mostra título e trecho.
import('/pagefind/pagefind.js')
  .then(function (m) { return m.search(term); })
  .then(function (r) { return Promise.all(r.results.slice(0, 8).map(function (x) { return x.data(); })); })

Um efeito colateral de que eu gosto: o termo buscado nunca chega ao servidor como query string, então não vai parar num access log. O formulário fica escondido de propósito para navegadores sem JavaScript – um envio normal do formulário teria colocado o termo na URL.

A lição: “estático” não quer dizer “sem interação”. Quer dizer que a interação acontece no navegador do leitor, com dados preparados com antecedência.

✍️ Meu fluxo de trabalho para um post novo

  1. Escrever o arquivo Markdown em site/content/en/posts/<slug>.md com o front matter acima. As traduções recebem o mesmo nome de arquivo, a mesma translationKey e tags com um sufixo de idioma (hugo-de, hugo-fr, …).
  2. Adicionar a imagem em site/uploads/YYYY/MM/ – WebP, no máximo 1536 px de largura, abaixo de 280 KB. Dentro do texto, as imagens são referenciadas como /wp-content/uploads/YYYY/MM/name.webp, o endereço que o WordPress usava.
  3. Build:
tools/build.sh

Ele roda check_posts.py, depois hugo --gc --minify, depois imgattrs.py, depois o Pagefind. O Hugo sozinho leva uns dez segundos para o site inteiro.

  1. Publicar:
tools/deploy.sh <host> 10022

O rsync envia o build para uma pasta incoming/; o servidor então o copia para uma nova pasta de release e aponta um symlink para ela num único passo. As últimas cinco releases ficam guardadas, então tools/deploy.sh <host> 10022 rollback volta em um segundo. A chave de deploy não consegue fazer mais nada – o servidor só aceita exatamente esses comandos para ela.

  1. Commit e push do repositório de conteúdo.

Dois repositórios: código aberto, conteúdo privado

O servidor e as ferramentas de build ficam num repositório público, www_hugo, ao lado do código Ansible para todo o resto. O conteúdo – posts, imagens, templates, rascunhos – fica num privado. O motivo é que um repositório lembra de tudo: uma imagem que eu tiro do ar ficaria para sempre no histórico de um repo público, e rascunhos não são para os leitores. O servidor só recebe arquivos prontos pelo passo de deploy e nunca vê um rascunho; o repo público nunca vê o conteúdo.

A lição: publicar são dois passos independentes. O servidor mostra o que foi deployado por último, o Git guarda o que foi commitado por último – eu faço os dois, nessa ordem.

⬆️ Atualizando o Hugo

O Hugo nem está instalado no servidor. Ele vive como um único binário em .tools/ na máquina que faz o build do site, junto com o Pagefind. As versões são fixadas no versions.yml do repo público:

hugo_version:                "0.169.0"   # github.com/gohugoio/hugo/releases
pagefind_version:            "1.6.0"     # github.com/Pagefind/pagefind/releases

Uma atualização segue o mesmo padrão de todo o resto aqui:

  1. Ler as release notes – o Hugo deprecia funções de template de vez em quando e avisa sobre elas na saída do build muito antes de removê-las.
  2. Baixar a release extended para Linux, comparar o SHA-256 com o arquivo de checksums da release, substituir .tools/hugo.
  3. Fazer o build numa pasta separada e compará-lo com o build anterior (diff -r). Só diferenças esperadas devem aparecer.
  4. Mudar o pin no versions.yml, deploy, commit.

Como o servidor só serve arquivos, uma atualização do Hugo nunca consegue quebrar o site no ar. O pior caso é um build que falha ou fica com outra cara – e isso acontece na minha máquina, não na frente dos leitores.

A lição: o gerador é uma ferramenta de build, como um compilador. Fixe a versão, atualize de propósito e compare a saída.

🤖 O que o Claude faz em torno do Hugo

A maior parte do trabalho neste blog é feita junto com o Claude (a IA da Anthropic) no terminal. Dividido por tema:

  • Migração: export do WordPress, conversão de cada post para Markdown com front matter, endereços antigos e caminhos de imagens mantidos, redirects para slugs alterados.
  • Templates e visual: reconstrução do tema antigo em templates do Hugo, o slider, a sidebar, os cantos escuros como as páginas de arquivo por data.
  • SEO: o partial head.html, o sitemap com hreflang, dados estruturados, imagens de prévia abaixo do limite do WhatsApp.
  • Escrever e traduzir: rascunhos com as minhas palavras, traduções para todos os oito idiomas com regras fixas (blocos de código idênticos byte a byte, links reescritos por idioma) e um verificador que compara cada tradução com o original em inglês.
  • Verificações: a verificação do build, uma checagem de links em todas as páginas geradas, uma checagem ao vivo contra o site em execução.
  • Servidor e deploy: a role do Ansible para o nginx, o deploy atômico, SELinux, monitoramento.
  • Troubleshooting: descobrir por que um post não apareceu (veja a próxima seção) ou por que um breadcrumb apontava para uma página inexistente.

O que fica comigo: decidir o que é escrito e publicado, ler cada rascunho, rodar os playbooks, e cada push e deploy – o Claude pergunta antes de cada um.

A lição: um site estático é feito de arquivos de texto e pequenos scripts – exatamente o material com que um assistente de IA lida bem. As decisões continuam sendo minhas.

🐛 Armadilhas que só apareceram na operação

  1. Um post do futuro não entra no build. Coloquei a data de um post às 15:50 e fiz o build às 15:44 – o Hugo o deixou de fora em silêncio. Nenhum erro, o post simplesmente não estava lá. date precisa estar no passado, ou o build precisa de --buildFuture.
  2. Uma página de dia faltando. O breadcrumb de um post novo apontava para o arquivo do dia dele (/2026/11/13/), que não existia porque as páginas de data são arquivos de conteúdo, não páginas geradas. A checagem de links achou; agora uma data nova precisa do seu _index.md. E enquanto eu escrevia justamente este post, os dois erros aconteceram de novo: o post estava datado 08:30 e o build foi às 08:22, e a nova página do dia dele tinha 12:00 – uma página datada ao meio-dia fica no futuro a manhã inteira.
  3. HTML convertido é frágil. Os posts importados do WordPress são uma mistura de Markdown e HTML cru. Em alguns deles, palavras ficaram grudadas ou um ** perdido sobreviveu. Só uma checagem das páginas renderizadas em todos os idiomas os encontrou.
  4. As configurações de tipografia importam. O typographer do Hugo transforma -- em travessão por padrão. O WordPress não fazia isso, então comandos como --check teriam virado –check em posts antigos. A configuração agora só mexe em aspas e apóstrofos.
  5. Nem tudo deve ir para a busca e os feeds. O imprint e a política de privacidade contêm o endereço postal. Eles são noindex, ficam fora dos feeds RSS e do índice do Pagefind – um plugin precisaria de uma configuração para cada uma dessas coisas, aqui é uma condição nos templates.
  6. Alguns endereços vêm do front matter. Alguns posts antigos têm uma chave url: com o caminho completo. Nas traduções ela precisa do prefixo de idioma, senão todos os idiomas reivindicam o mesmo endereço.

A lição: o Hugo faz exatamente o que mandam e quase nunca reclama. As verificações que os plugins do WordPress faziam em silêncio precisam ser escritas – e aí elas rodam em todo build.

📊 Medido

Posts146, em 8 idiomas
Páginas HTML geradascerca de 23.000 (posts, tags, categorias, arquivos)
Build do Hugocerca de 10 s (site inteiro)
Pasta de saída498 MB, quase tudo imagens
Índice de busca18 MB para 8 idiomas, carregado em pequenos pedaços
Software no servidor para o blognginx

🎯 As lições

  • Decida onde o trabalho acontece: na visita (WordPress) ou na publicação (Hugo).
  • Verifique o que um plugin realmente fazia antes de substituí-lo – a maior parte é um template, uma parte é uma verificação que você mesmo precisa escrever.
  • Busca, feeds e sitemaps funcionam sem servidor quando o build prepara os dados.
  • Fixe a versão do gerador como a de qualquer outra ferramenta de build e compare a saída antes do deploy.
  • Um post que some sem nenhuma mensagem de erro geralmente tem uma data no futuro.
  • Mantenha conteúdo e código separados quando o código é público.
Alguns textos e imagens deste site foram criados com a ajuda de IA ou gerados por IA. Detalhes