felipeweber.com – felipeweber.com

Publicando um site Hugo na Cloudflare Pages sem dor de cabeça

weberecomp@gmail.com (Felipe Weber) — Wed, 02 Sep 2026 00:00:00 +0000

Colocar um site estático no ar deixou de ser um projeto. O que ainda consome tempo é a primeira meia hora — a que separa “funciona na minha máquina” de “funciona em produção com HTTPS e deploy automático”.

Este é o caminho que uso hoje.

O contrato mínimo

A Cloudflare Pages precisa de três coisas: um repositório Git, um comando de build e um diretório de saída. Para Hugo:

# Build command
hugo --gc --minify

# Build output directory
public

O resto é configuração de ambiente. E é aqui que quase todo primeiro deploy falha.

Armadilha 1: a versão do Hugo

O runner da Pages não usa a mesma versão que você tem localmente. Sem fixar, você recebe uma versão antiga — normalmente sem o build extended, o que quebra qualquer tema que use SCSS.

Defina a variável de ambiente no painel do projeto:

HUGO_VERSION = 0.165.0

Fixe a versão no repositório também, num arquivo que o time consiga ler. Uma variável de ambiente invisível é uma dívida técnica esperando acontecer.

Armadilha 2: Hugo Modules precisa de Go

Se o tema vem como Hugo Module — e hoje a maioria vem — o runner precisa do Go disponível antes do hugo rodar:

GO_VERSION = 1.27.1

Sem isso o build morre com um module not found que não diz nada sobre a causa real.

Armadilha 3: `baseURL` e os previews

Cada branch gera uma URL de preview própria. Se o baseURL estiver cravado no config, os links absolutos do preview apontam para produção. A saída é deixar a própria Pages injetar o valor:

hugo --gc --minify --baseURL "$CF_PAGES_URL"

Em produção o CF_PAGES_URL é o domínio final, então o comando serve para os dois casos sem if.

O que você ganha de graça

Feito isso, cada git push na main vira um deploy. Branches viram previews. O certificado é emitido e renovado sozinho. E o custo continua zero até um volume de tráfego que a maioria dos blogs pessoais nunca vai ver.

A documentação oficial está em developers.cloudflare.com/pages e vale a leitura da seção de build configuration antes do primeiro deploy.

Hugo Modules na prática: temas versionados sem submódulos

weberecomp@gmail.com (Felipe Weber) — Tue, 18 Aug 2026 00:00:00 +0000

Todo tutorial de Hugo começa com git submodule add. Funciona, mas transforma o tema numa cópia congelada dentro do seu repositório, sem versão declarada e sem caminho de upgrade.

Hugo Modules resolve isso tratando o tema como o que ele é: uma dependência.

O setup

hugo mod init github.com/seu-usuario/seu-site
hugo mod get github.com/imfing/hextra

O go.mod gerado registra a versão exata:

module github.com/seu-usuario/seu-site
go 1.27.1
require github.com/imfing/hextra v0.12.3

No config, o import substitui o antigo theme::

module:
 imports:
 - path: github.com/imfing/hextra

Por que isso é melhor

Upgrade vira um comando, e rollback também:

hugo mod get -u github.com/imfing/hextra # última versão
hugo mod get github.com/imfing/hextra@v0.12.3 # volta para uma específica

Nenhum arquivo do tema entra no seu repositório. O diff de um upgrade é uma linha no go.mod.

Override arquivo a arquivo

A parte que mais me convenceu: os arquivos do projeto vencem os do módulo, um a um. Se você quer trocar só o rodapé, cria só o rodapé:

layouts/_partials/footer.html

O resto do tema continua vindo do módulo e continua recebendo correções nos upgrades. Comparado a copiar o tema inteiro para dentro do repo, a diferença de manutenção é enorme.

A regra prática: se você copiou mais de três arquivos do tema, revise se o problema não é de configuração.

O custo

Você precisa do Go instalado — localmente e no CI. É o preço de entrada, e vale, porque a partir daí o tema para de ser um bloco opaco no seu histórico de commits.

O código do Hextra está em github.com/imfing/hextra e serve de referência boa para ver como um tema modular se organiza.

Um índice de busca estático que cabe em 40 KB

weberecomp@gmail.com (Felipe Weber) — Tue, 04 Aug 2026 00:00:00 +0000

Busca em site estático tem três caminhos: serviço externo pago, servidor próprio, ou um índice JSON gerado no build e consultado no navegador. Para um blog, o terceiro é quase sempre o certo — desde que o índice não engorde.

O que faz o índice crescer

O erro comum é indexar o conteúdo inteiro de cada post. Cinquenta artigos de 1.500 palavras viram um JSON de vários megabytes, que o visitante baixa antes de digitar a primeira letra.

O que realmente importa para uma busca de blog:

Campo	Serve para	Custo
título	achar o post	baixíssimo
descrição	contexto no resultado	baixo
headings	achar a seção	baixo
corpo completo	achar uma frase exata	altíssimo

Na prática, título + descrição + headings resolvem quase toda busca real e mantêm o índice em dezenas de kilobytes.

Gerando o índice no build

Em Hugo, o índice é só mais um template de saída. A parte relevante:

{{- $index := slice -}}
{{- range where site.RegularPages "Section" "blog" -}}
 {{- $index = $index | append (dict
 "title" .Title
 "url" .RelPermalink
 "desc" .Description
 "headings" (apply .Fragments.Headings "index" "." "Title")
 ) -}}
{{- end -}}
{{ $index | jsonify }}

Nenhum passo extra no pipeline: o arquivo nasce junto com o HTML.

Carregue tarde

O índice não precisa existir no primeiro paint. Busque no primeiro foco do campo:

let indexPromise;

input.addEventListener("focus", () => {
 indexPromise ??= fetch("/search-index.json").then((r) => r.json());
}, { once: true });

Quem nunca usa a busca nunca paga por ela. Quem usa paga uma vez, e o navegador cacheia.

A melhor otimização continua sendo não baixar o arquivo.

Onde isso quebra

Se o seu caso de uso é achar uma frase exata dentro de um artigo longo — um manual, uma base de conhecimento — o índice reduzido não serve. Aí vale avaliar Pagefind, que fragmenta o índice e baixa só os pedaços necessários.

Para um blog, é otimizar um problema que você não tem.

Dark mode sem flash: o que acontece antes do primeiro paint

weberecomp@gmail.com (Felipe Weber) — Tue, 21 Jul 2026 00:00:00 +0000

Você implementa dark mode, testa, funciona. Aí recarrega a página e vê um lampejo branco antes do tema escuro aparecer. O famoso FOUC.

A causa não está no CSS. Está em quando o JavaScript roda.

A corrida

O navegador monta a página em ordem: lê o HTML, encontra o CSS, calcula o estilo, pinta. Se o script que decide o tema roda depois dessa pintura, o usuário vê o tema padrão primeiro.

parse HTML → carrega CSS → primeiro paint → DOMContentLoaded → seu script
▲ │
flash acontece aqui aplica o tema aqui

Qualquer script com defer, async ou preso ao DOMContentLoaded perde a corrida por construção.

A correção

Um script síncrono e inline, no <head>, antes de qualquer folha de estilo que dependa do tema:

<script>
 (function () {
 var stored = localStorage.getItem("color-theme");
 var theme = stored === "light" || stored === "dark"
 ? stored
 : (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light");
 document.documentElement.classList.add(theme);
 document.documentElement.style.colorScheme = theme;
 })();
</script>

Ele bloqueia o parser por menos de um milissegundo e a classe já está no <html> quando o primeiro pixel aparece.

Os dois detalhes que quase todo mundo esquece

color-scheme. Sem ele, o navegador continua pintando as barras de rolagem, os campos de formulário e o fundo padrão em claro. É uma linha, e é a diferença entre “escuro” e “escuro de verdade”.

localStorage pode explodir. Em modo privado de alguns navegadores, o acesso lança exceção. Envolva em try/catch — o site precisa carregar mesmo quando a preferência não pode ser lida.

Três estados, não dois: claro, escuro e sistema. “Sistema” é o padrão correto, e é o único que respeita quem mudou a preferência no sistema operacional depois de visitar seu site.

Verificando

O teste honesto é com throttling de CPU ligado, em 6x slowdown, com o cache desabilitado. O flash que você não vê no seu desktop aparece na hora em um celular intermediário.

Escrevendo CSS que sobrevive ao próximo redesign

weberecomp@gmail.com (Felipe Weber) — Tue, 30 Jun 2026 00:00:00 +0000

Todo projeto de frontend chega no ponto em que ninguém quer mexer no CSS. Não porque está mal escrito — porque ninguém sabe o que quebra.

O sintoma é sempre o mesmo: a mesma decisão está escrita em quinze lugares.

Tokens antes de componentes

Antes de estilizar qualquer coisa, defina o vocabulário:

:root {
 --surface: #faf7f0;
 --text: #23201c;
 --text-muted: rgb(35 32 28 / 62%);
 --accent: #9a5b18;
 --radius: 8px;
 --measure: 68ch;
}

Trocar o tema inteiro passa a ser trocar esse bloco. Sem tokens, é um find-and-replace com risco.

Um tema, uma inversão

Dark mode não é um segundo CSS. É a mesma folha com os tokens redefinidos:

html.dark {
 --surface: #1a1714;
 --text: #ece7de;
 --accent: #e2a05a;
}

Se você precisou escrever uma regra html.dark .componente { ... }, o componente está lendo uma cor que deveria ser um token.

`color-mix` mata a paleta de doze tons

Metade das variáveis de um design system são variações de opacidade da mesma cor. color-mix gera isso na hora:

.card {
 border: 1px solid color-mix(in srgb, var(--text) 12%, transparent);
}

.card:hover {
 border-color: color-mix(in srgb, var(--accent) 48%, transparent);
}

A borda acompanha o tema sozinha, nos dois modos, sem nenhuma variável nova.

Medida de leitura é uma decisão, não um acidente

.prose { max-width: 68ch; line-height: 1.7; }

Duas linhas que fazem mais pela legibilidade do que qualquer escolha de fonte. ch acompanha o tamanho do texto — se a fonte cresce, a medida cresce junto.

Se você não consegue explicar por que um valor é 1.7 e não 1.5, ele vai virar 1.6 no próximo PR e ninguém vai saber dizer se melhorou.

O teste

Pegue o CSS e tente mudar a cor de acento do site inteiro. Se der para fazer em uma linha, ele sobrevive ao próximo redesign. Se precisar abrir cinco arquivos, você já sabe onde começar a refatorar.

Medindo Core Web Vitals de verdade em um site estático

weberecomp@gmail.com (Felipe Weber) — Thu, 14 May 2026 00:00:00 +0000

Site estático tem uma vantagem injusta em performance: não há servidor pensando, não há hidratação, não há waterfall de API. É fácil tirar 100 no Lighthouse.

E é exatamente por isso que o número engana.

Lab não é campo

O Lighthouse roda uma simulação: uma máquina, uma rede, um carregamento frio. Os Core Web Vitals que o Google usa vêm do CrUX — usuários reais, aparelhos reais, redes reais, no percentil 75.

Os dois discordam com frequência, e o campo é quem manda.

Medição	Onde vive	O que responde
Lighthouse	seu terminal / CI	“eu regredi desde o último commit?”
CrUX	dados reais agregados	“meus visitantes estão sofrendo?”
RUM próprio	seu site	“quais páginas, quais aparelhos?”

As três métricas, em uma frase cada

LCP — quando o maior elemento visível terminou de pintar. Num blog, quase sempre é o título ou a primeira imagem. Fonte web mal configurada atrasa isso mais do que qualquer imagem.

INP — quanto tempo a página leva para responder a uma interação. Site estático raramente falha aqui, a menos que algum script de terceiro esteja segurando a thread principal.

CLS — o quanto o conteúdo pula durante o carregamento. Causa número um: imagem sem width/height. Causa número dois: fonte que troca e muda a altura do texto.

Medindo no seu próprio site

A biblioteca oficial cabe em poucas linhas e reporta números reais:

import { onLCP, onINP, onCLS } from "web-vitals";

function send(metric) {
 navigator.sendBeacon("/vitals", JSON.stringify({
 name: metric.name,
 value: metric.value,
 rating: metric.rating,
 path: location.pathname,
 }));
}

onLCP(send);
onINP(send);
onCLS(send);

sendBeacon não segura a navegação — o envio acontece mesmo quando o usuário já saiu da página.

O que corrigir primeiro num site estático

Fontes. font-display: swap, preload só nos arquivos usados acima da dobra, e servidas do seu domínio.
Dimensões de imagem. Sempre width e height, mesmo com CSS responsivo por cima.
Scripts de terceiro. Cada um deles é um risco de INP que você não controla.

Otimizar de dentro para fora: primeiro o que você serve, depois o que você pede emprestado.

A referência boa continua sendo web.dev/vitals, que acompanha as mudanças de definição das métricas ao longo do tempo.