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.

🌐 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
| Pergunta | WordPress | Hugo |
|---|---|---|
| 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 Redis | Só o servidor web |
| Superfície de ataque | Login, admin, plugins, XML-RPC, PHP | Arquivos estáticos |
| Atualizações regulares | Core, plugins, temas, PHP | nginx; Hugo só na máquina de build |
| Onde eu escrevo? | Editor no navegador | Editor de texto, Git |
| Comentários, formulários | Embutidos | Precisam de um serviço externo |
| Velocidade | Com cache: 58 ms para a página inicial | 57 ms – nenhuma diferença |
| Peso da página (inicial, sem imagens) | 25 arquivos, 198 KB | 3 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 WordPress | Tarefa | Agora |
|---|---|---|
| Yoast SEO | Título, description, canonical, Open Graph, dados estruturados | head.html (um template para todas as páginas) |
| Yoast SEO | Sitemap | Embutido no Hugo, template sitemap.xml próprio com hreflang |
| Yoast SEO | “Seu post não tem description” | check_posts.py: o build para |
| Polylang | Idiomas, seletor de idioma | Embutido no Hugo |
| CompressX | Imagens WebP, tamanhos menores | Processamento de imagens do Hugo |
| Autoptimize | Minificar CSS, JS, HTML | hugo --minify |
| WP Super Cache, Redis | Cache de página e de objetos | Desnecessário – toda página já é um arquivo |
| Busca (WordPress) | Busca full-text | Pagefind (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.pyadicionasrcsete 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.
- 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 comdata-pagefind-ignore. Ele detecta o idioma pelo atributolange monta um índice por idioma. - O índice é dividido em muitos arquivos pequenos em
/pagefind/– 18 MB no total para oito idiomas. Ninguém baixa tudo. - 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
- Escrever o arquivo Markdown em
site/content/en/posts/<slug>.mdcom o front matter acima. As traduções recebem o mesmo nome de arquivo, a mesmatranslationKeye tags com um sufixo de idioma (hugo-de,hugo-fr, …). - 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. - 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.
- 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.
- 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:
- 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.
- Baixar a release extended para Linux, comparar o SHA-256 com o arquivo de checksums da release, substituir
.tools/hugo. - Fazer o build numa pasta separada e compará-lo com o build anterior (
diff -r). Só diferenças esperadas devem aparecer. - 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 comhreflang, 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
- 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á.
dateprecisa estar no passado, ou o build precisa de--buildFuture. - 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. - 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. - 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--checkteriam virado–checkem posts antigos. A configuração agora só mexe em aspas e apóstrofos. - 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. - 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
| Posts | 146, em 8 idiomas |
| Páginas HTML geradas | cerca de 23.000 (posts, tags, categorias, arquivos) |
| Build do Hugo | cerca de 10 s (site inteiro) |
| Pasta de saída | 498 MB, quase tudo imagens |
| Índice de busca | 18 MB para 8 idiomas, carregado em pequenos pedaços |
| Software no servidor para o blog | nginx |
🎯 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.
