No primeiro post desta série, discutimos como a arquitetura JAMstack e os Geradores de Sites Estáticos (SSG) estão resolvendo problemas crônicos de lentidão e segurança na web. Hoje, vamos escolher a nossa arma: o Hugo.

Existem excelentes SSGs no mercado, como Next.js e Jekyll, mas o Hugo tem um diferencial que atrai engenheiros do mundo todo: velocidade absurda.

Criado na linguagem Go (Golang) pelo ex-engenheiro do Google, Steve Francia, o Hugo consegue compilar páginas em menos de 1 milissegundo por página. Se você tem um blog de mil páginas, o Hugo gera o site inteiro em uma fração de segundo. Mas como ele organiza essa mágica?

A Anatomia de um Projeto Hugo

Diferente de frameworks pesados de JavaScript que possuem um buraco negro chamado node_modules, a estrutura de um projeto Hugo é extremamente limpa, lógica e focada em convenção.

Se fizermos um “Raio-X” na raiz de um projeto, encontraremos quatro pilares fundamentais:

  • 📁 content/ (Onde a mágica é escrita): Aqui ficam os seus arquivos de texto em formato Markdown. Cada artigo, página “Sobre” ou termo de uso vive aqui. É a separação perfeita entre o conteúdo e o design.
  • 📁 layouts/ (O Cérebro da Interface): Contém os templates em HTML misturados com variáveis em Go. É aqui que o Hugo pega o seu arquivo Markdown e “veste” ele com a estrutura da página.
  • 📁 data/ (O Banco de Dados sem Servidor): Uma pasta genial onde você pode colocar arquivos YAML ou JSON estruturados. O Hugo lê esses arquivos durante o build. É perfeito para armazenar listas de habilidades, currículos ou catálogos sem precisar de um banco de dados real.
  • 📄 hugo.yaml (O Painel de Controle): O arquivo de configuração principal onde definimos menus, idioma, URL base e quais módulos/temas o site vai usar.

O Grande “Pulo do Gato”: static vs assets

Se você está começando com o Hugo, existe uma “pegadinha” clássica de arquitetura que confunde muitos desenvolvedores. Qual é a diferença entre as pastas static/ e assets/?

A resposta define como o Hugo processa (ou não) os seus arquivos:

  1. A pasta static/: Tudo o que você joga aqui (como logo.png ou robots.txt) é copiado exatamente como está para a pasta final do site. O Hugo não mexe nesses arquivos. Eles vão direto para a raiz do servidor.
  2. A pasta assets/: Esta pasta aciona uma ferramenta poderosa chamada Hugo Pipes. Arquivos colocados aqui (como arquivos SCSS ou JavaScript modernos) serão processados, minificados, compilados e concatenados pelo Hugo antes de ir para a versão final.

Muitos desenvolvedores quebram seus layouts por tentar usar Hugo Pipes em arquivos que estão na pasta estática, ou vice-versa. Entender essa diferença é o divisor de águas entre um site que apenas funciona e um site altamente otimizado.

O Próximo Passo

Agora que entendemos o motor que roda por baixo do capô, chegou a hora de sujar as mãos de graxa.

No terceiro post desta série, vamos sair da teoria e ir para a prática: instalaremos o Hugo do zero e faremos o deploy automatizado da nossa aplicação diretamente na infraestrutura de nuvem do Cloudflare Pages.

Você prefere escrever o conteúdo do seu site direto em código (Markdown) ou não abre mão de painéis de controle visuais (CMS)? Me conte nos comentários!