figueirego. – figueirego

Construindo meu blog, parte 1: escrever sem manter um backend

Tue, 13 Oct 2026 12:03:00 -0300

Este blog começa com arquivos de texto. O Hugo lê esses arquivos, aplica os layouts e gera as páginas que chegam ao navegador. Eu não preciso manter uma API de publicação nem um banco de dados próprio para servir os artigos.

Essa era a condição principal quando comecei: queria um lugar para explicar o que construo, registrar decisões e voltar a elas depois. Também queria que o espaço tivesse a identidade do figueirego, fosse confortável no celular e permitisse ler em português ou inglês.

Entre a primeira referência e a versão publicada, houve decisões sobre design, navegação, comentários, busca, hospedagem e imagens. Dividi o relato em três partes para explicar o conjunto sem misturar todas as responsabilidades:

Arquitetura: por que escolhi essa base e o que cada componente faz.
Experiência de leitura: organização, idiomas, busca, temas e comentários.
Publicação e operação: do Markdown ao domínio público, incluindo imagens e estatísticas.

A referência foi o Akita; o resultado precisava ser meu

O ponto de partida foi Meu Novo Blog — Como Eu Fiz, do Fabio Akita. O que me interessou foi a escolha de publicar arquivos Markdown como um site estático e reduzir o trabalho de manter uma engine própria. A prioridade era conseguir escrever.

Eu gostei da proposta técnica, mas queria outra direção visual: as cores do meu site, a minha marca e uma organização pensada para os conteúdos que pretendo produzir. Separar essas duas decisões ajudou. Adotar Hugo não me obrigava a reproduzir a aparência de outro blog.

Também precisei corrigir uma confusão de nomes logo no começo: Hugo é o gerador; Hextra é o tema. O Hugo é escrito em Go. O Hextra fornece uma base de layouts e recursos sobre a qual o blog pode ser construído. O repositório do Hextra documenta essa relação.

O que acontece quando alguém abre um artigo

A página já está gerada quando o leitor chega. A hospedagem entrega HTML, CSS, JavaScript e os arquivos necessários. Não há uma consulta ao meu banco de dados para montar o texto a cada acesso.

O caminho principal é este:

Texto em Markdown + metadados + layouts
 ↓
 Hugo
 ↓
 páginas estáticas
 ↓
 Hostinger
 ↓
 navegador do leitor

Isso não transforma o blog em uma página sem comportamento. A busca roda no navegador, os filtros respondem a cliques, o tema muda e os comentários vêm de um serviço externo. A distinção útil está no que preciso operar: o conteúdo principal não depende de um servidor de aplicação meu em execução.

Escolhi essa estrutura porque ela atende ao tipo de publicação que quero fazer. Não estou construindo uma plataforma com contas próprias de leitores, cobrança de assinaturas ou edição simultânea no navegador. Se essas necessidades aparecerem, merecerão uma decisão específica.

Uma função clara para cada ferramenta

A implementação ficou dividida assim:

Componente	Responsabilidade neste blog
Markdown	Guardar os textos e seus metadados.
Hugo + Hextra	Gerar as páginas e fornecer a base visual e funcional.
Layouts, CSS e JavaScript próprios	Aplicar a identidade e os comportamentos específicos do figueirego.
GitHub privado	Versionar o código-fonte e executar as verificações e o build.
Hostinger	Servir o site estático no domínio público.
Amazon S3	Guardar imagens enviadas separadamente do site.
Disqus	Hospedar a conversa e a moderação dos comentários.
GoatCounter	Registrar visitas usadas na geração dos mais lidos.

Uma decisão importante foi aproveitar a hospedagem que eu já tinha. Cheguei a considerar outros destinos, mas o blog foi publicado na Hostinger. A AWS entrou para as imagens, não como hospedagem das páginas. Não há uma distribuição CloudFront fazendo parte deste fluxo.

Os arquivos-fonte permanecem em um repositório privado. O leitor recebe o resultado publicado; não precisa de acesso ao repositório. Isso também não torna secretos os arquivos que envio ao site: textos, imagens, HTML e JavaScript servidos ao navegador são públicos.

O tema é uma base que posso personalizar

Nesta primeira versão, fixei Hugo Extended 0.167.0 e Hextra 0.13.0. O tema está incluído no repositório. Para gerar este projeto com o binário instalado do Hugo, não preciso instalar Go ou executar um build npm local.

As personalizações ficam separadas da pasta do tema:

content/ textos em português e inglês
layouts/ páginas e componentes personalizados
assets/ estilos, busca e interações
static/ fontes, marca e imagens locais
i18n/ mensagens da interface
themes/hextra/ base do tema
scripts/ upload e verificações auxiliares

Essa separação deixa mais claro onde procurar um problema. Um texto incorreto vai para content/. Uma mensagem do botão em inglês vai para i18n/. Um espaçamento ou contraste vai para os estilos. Uma mudança no serviço de comentários fica na integração correspondente.

Atualizar o tema no futuro ainda exigirá revisão. Separar os arquivos torna o trabalho mais compreensível; não garante compatibilidade automática com qualquer versão nova.

Onde eu escrevo, afinal?

Essa foi uma das dúvidas durante a construção. Não existe uma aba administrativa dentro do blog em que eu entro e começo a digitar. A edição acontece no computador, em arquivos Markdown, usando um editor de texto ou de código.

Cada publicação tem um cabeçalho com título, data, resumo, temas e estado de rascunho. Depois vem o texto. O conteúdo continua editável sem abrir um serviço de edição específico, e o Git registra as alterações que eu decido salvar em commits.

Para revisar, uso a prévia local do Hugo. Ela mostra a página com o layout real e permite incluir rascunhos. Publicar é outra etapa: enviar o conteúdo revisado, gerar a versão de produção e conferir o domínio público. Os comandos completos estão na terceira parte.

O texto do Akita sobre Docker também entrou nessa investigação. Ali, Docker prepara um ambiente local para contribuir com o repositório. Rodar essa cópia não publica automaticamente no site dele; uma contribuição segue por pull request. No meu fluxo atual, uso o Hugo localmente, sem adicionar Docker como requisito.

Idiomas entraram na estrutura desde o começo

Eu queria inglês na raiz do domínio e português em /pt/. Isso virou organização de conteúdo: cada idioma tem seus arquivos, ligados por uma chave de tradução estável.

O relato do Akita sobre traduzir seu acervo foi outra referência. No meu caso, estou começando com pares de textos, em vez de migrar um arquivo histórico. O botão de idioma navega entre versões já preparadas; não chama um tradutor a cada clique.

Isso coloca a revisão no processo editorial. Título, explicações e exemplos precisam continuar fazendo sentido nos dois idiomas. A infraestrutura conecta os arquivos, mas não decide se a tradução está boa.

Construir com IA também exigiu conferir o resultado

Usei o Codex como apoio para transformar as decisões em código, revisar comportamentos e organizar esta série. Para mostrar o resultado, esta série usa capturas reais das telas, identificadas por contexto nas legendas. O processo teve prévias, capturas de tela, pedidos de ajuste e verificações do site servido.

Algumas correções nasceram do uso direto: o botão de busca que não abria como esperado, os comentários que apareciam separados por idioma e o espaço excessivo no rodapé. Nenhuma delas seria resolvida apenas por escolher uma tecnologia adequada.

A construção chegou a incluir propostas de newsletter e novas divisões no menu. A newsletter saiu por enquanto; os formatos ficaram dentro do Arquivo. Ter uma possibilidade na implementação não significava que ela precisava entrar na primeira versão.

O próximo passo já é usar essa estrutura para escrever. Para entender como ela se apresenta a quem chega ao blog, siga para a parte 2: experiência de leitura.

Série Construindo meu blog: 1. Arquitetura · 2. Experiência de leitura · 3. Publicação e operação.

Construindo meu blog, parte 2: a experiência de quem lê

Tue, 13 Oct 2026 12:02:00 -0300

Nota editorial: Esta série registra a construção inicial do blog em Hugo, separado do portfólio. A versão unificada do site reúne os dois em figueirego.com, com o blog em /blog/ (inglês) e /pt/blog/ (português). A navegação e as capturas abaixo documentam aquela etapa inicial.

Um leitor chega para encontrar um texto. Talvez lembre do assunto, talvez queira ver o que publiquei por último, talvez tenha recebido um link. A organização do blog precisa atender esses caminhos sem exigir que ele entenda como eu organizo meus arquivos.

Essa foi a parte mais iterativa da construção. Eu queria a simplicidade da base apresentada pelo Akita, com a identidade do meu site e uma experiência própria. Cores e fontes foram o começo; as decisões mais importantes apareceram na navegação, na busca e nos comentários.

Na primeira parte, explico a arquitetura. Aqui, o foco é o que acontece depois que a página abre.

A identidade precisava continuar sendo figueirego

Usei os SVGs da marca já presentes no meu site, com versões para fundos claros e escuros. Isso preserva o desenho da logo. Para títulos, interface e texto, mantive Manrope; para código, JetBrains Mono. Os arquivos das fontes são servidos pelo próprio blog.

O verde-petróleo marca links e ações no tema claro. No escuro, o destaque fica mais claro, próximo do turquesa, para continuar visível sobre o fundo. O conteúdo usa superfícies discretas, divisores e espaço entre blocos.

O cabeçalho recebeu o efeito de vidro que eu também queria no site: fundo translúcido, desfoque e uma borda leve. Há uma alternativa sólida para navegadores sem suporte e para quem prefere reduzir transparências. O efeito acompanha a leitura; não deve dificultá-la.

Quatro caminhos na barra superior

A organização passou por versões com Artigos, Notas e Experimentos no topo. Conforme surgiram Respostas e Transcrições, ficou claro que colocar cada formato na barra aumentaria a disputa por espaço, especialmente no celular.

Na versão independente descrita aqui, a navegação final ficou assim:

Recentes: todas as publicações, da mais nova para a mais antiga.
Arquivo: o conjunto completo, com filtros para encontrar um texto específico.
Sobre: minha apresentação e os links para me encontrar.
Meu site: acesso ao figueirego.com, na versão correspondente ao idioma atual.

Os links externos abrem em outra aba. Dentro do blog, a navegação continua na mesma. No celular, o cabeçalho reorganiza os controles e a navegação em linhas, preservando áreas de toque e rótulos acessíveis.

Formato e tema respondem perguntas diferentes

Um artigo sobre Go pode compartilhar assunto com um experimento e com uma resposta a alguém. Por isso, mantive os formatos separados dos temas:

Formato	Quando pretendo usar
Artigos	Desenvolver uma ideia, uma decisão ou um processo com contexto.
Notas	Registrar uma observação ou um aprendizado mais curto.
Experimentos	Documentar uma tentativa, sua configuração e o que foi observado.
Respostas	Desenvolver uma pergunta recebida nas redes ou nos comentários.
Transcrições	Publicar versões em texto dos meus vídeos e conversas.

Os temas são as tags: engenharia de software, aprendizado, Go e outros assuntos que aparecerem nas publicações. Um texto pode ter mais de um tema sem precisar existir em várias cópias.

No Arquivo, o leitor combina formato, ano, tema e busca textual. Os filtros ficam no endereço, permitindo compartilhar aquela seleção e usar voltar ou avançar. Sem JavaScript, a lista completa continua disponível. As contagens dos temas vêm do conteúdo publicado; não preenchi a interface com números de demonstração.

Imagens ajudam quando têm uma função

Gostei da ideia de mostrar capas nas publicações. Elas ajudam a identificar um texto e podem antecipar um conceito, como um fluxo ou uma arquitetura. Decidi mantê-las opcionais: uma nota curta pode funcionar perfeitamente só com título e texto.

A publicação mais recente recebe mais espaço na home. As demais seguem com título, resumo e metadados, acompanhados de miniatura quando existe capa. Na página do artigo, a imagem aparece inteira, com texto alternativo e legenda quando informados.

Também registro suas dimensões para reservar espaço antes do carregamento. Para explicar esta construção, escolhi capturas reais do processo. A capa desta parte mostra o Arquivo na prévia local, já com os artigos desta série. A legenda identifica o ambiente: uma tela local ajuda a mostrar a interface, mas não comprova que aquela versão já foi publicada.

Buscar precisa encontrar o que está no texto

Durante as revisões, a busca virou um ponto de atenção: o botão precisava ter presença suficiente, abrir corretamente e permitir encontrar conteúdo além do título. Um controle bonito que trava interrompe o caminho do leitor.

A implementação usa FlexSearch no navegador, com um índice do idioma atual. Ela considera título, descrição, resumo, tags e texto completo. A normalização de acentos permite procurar publicacao e encontrar conteúdo com “publicação”. O botão e os atalhos Ctrl+K ou ⌘K abrem o diálogo.

Há duas buscas com objetivos diferentes. O campo do Arquivo filtra sua lista por título, resumo e temas. A busca do cabeçalho procura também dentro dos textos. Se alguém lembra de um trecho sobre translationKey, pode usar a segunda para encontrar este artigo.

A busca local acompanha o conteúdo gerado pelo Hugo. Isso exige JavaScript no navegador, mas dispensa um servidor de busca próprio.

Busca na prévia local por translationKey, antes da publicação da série.

Dois idiomas, uma publicação relacionada

Naquela versão, o inglês ocupava a raiz de blog.figueirego.com; o português ficava em /pt/ no mesmo subdomínio. Cada versão tem seu próprio Markdown. O seletor leva à tradução correspondente quando ela existe; ele não traduz o texto ao ser acionado.

A ligação entre as versões deste artigo é explícita:

translationKey: building-blog-reading

Os dois arquivos usam essa mesma chave, embora tenham títulos e endereços diferentes. Isso permite revisar a tradução como texto de verdade. Também significa que uma correção editorial precisa ser considerada nos dois idiomas.

O idioma não determina a aparência. Por padrão, o tema acompanha o sistema; um clique alterna entre claro e escuro e salva a preferência naquele navegador. As transições dos ícones respeitam a preferência por movimento reduzido.

Uma conversa para as duas versões

No teste inicial, trocar de idioma podia levar a uma conversa diferente. Para o mesmo artigo, eu preferi reunir os comentários: quem lê em inglês e quem lê em português participa da mesma discussão.

O Disqus usa uma identidade compartilhada entre as traduções, baseada na translationKey. Sua interface acompanha o idioma da página. O texto que cada pessoa escreveu permanece no idioma original.

Os comentários carregam automaticamente nas publicações elegíveis em produção. Se o carregamento falhar, há uma opção para tentar novamente. A prévia local não abre as discussões reais.

O tema exigiu um cuidado adicional. O editor do Disqus está dentro de um iframe de outro domínio. Depois que o leitor interage com ele, o blog preserva o componente ao trocar de tema, pois pode existir um comentário ainda não enviado. Nesse caso, oferece uma atualização manual. Vale enviar ou copiar o texto antes de usá-la.

É uma integração externa, com suas próprias opções de moderação, aparência e anúncios no plano escolhido. Ter um blog estático não elimina essas dependências; apenas evita que eu mantenha um backend de comentários.

Acompanhar sem acrescentar outra tarefa

Mantive o RSS no rodapé, com uma página que explica o recurso e permite copiar o endereço do feed. Os cinco formatos publicados entram no RSS do respectivo idioma. Quem usa um leitor de feeds pode acompanhar as novidades por ali.

A newsletter ficou de fora por enquanto. Já os Mais lidos dependem de dados reais e serão explicados na terceira parte, sobre publicação e operação.

Para experimentar a organização, abra o Arquivo e selecione o tema engenharia de software. Depois, procure translationKey no botão de busca e troque o idioma deste artigo. Esses caminhos são um teste mais útil da interface do que olhar apenas para uma captura da home.

Série Construindo meu blog: 1. Arquitetura · 2. Experiência de leitura · 3. Publicação e operação.

Construindo meu blog, parte 3: do Markdown à publicação

Tue, 13 Oct 2026 12:01:00 -0300

Nota editorial: Esta série registra a construção inicial do blog em Hugo, separado do portfólio. A versão unificada do site reúne os dois em figueirego.com, com o blog em /blog/ (inglês) e /pt/blog/ (português). Os comandos, as capturas e o fluxo main → published → blog.figueirego.com abaixo pertencem à versão independente; não descrevem a publicação do site unificado.

O arquivo que contém este texto está em content/pt/posts/. A versão em inglês fica em content/en/posts/. Para publicar, eu reviso os dois, gero o site, verifico o resultado e envio a alteração ao GitHub. A hospedagem recebe páginas prontas.

Era essa a experiência que eu procurava: conseguir escrever sem precisar cuidar de uma aplicação de publicação funcionando o tempo inteiro. Ainda há ferramentas e serviços envolvidos. A diferença está em saber qual trabalho cada um faz e em manter um caminho curto entre o texto e o leitor.

Esta é a terceira parte da construção do blog. Na primeira, expliquei a arquitetura; na segunda, as decisões de leitura e navegação. Aqui vou percorrer a publicação de ponta a ponta.

O editor é um arquivo no computador

Escrevo em Markdown, no editor de código. Para começar um artigo, uso o modelo que já está no repositório:

hugo new content content/pt/posts/meu-artigo.md --kind default
hugo new content content/en/posts/my-article.md --kind default

Os arquivos nascem como rascunhos. O cabeçalho do texto, chamado front matter, reúne os dados que o layout precisa. Um exemplo reduzido, seguindo as convenções deste projeto:

---
title: "Como publiquei meu blog"
date: 2026-10-13T09:00:00-03:00
draft: true
sample: false
author: "Matheus Figueirêdo"
translationKey: "how-i-published-my-blog"
description: "Da escrita em Markdown à publicação."
summary: "As decisões e o fluxo para colocar o blog no ar."
tags: ["engenharia de software", "Hugo"]
image: "/images/minha-capa.webp"
imageAlt: "Tela do Arquivo do blog, com publicações organizadas por ano."
imageCaption: "Captura da prévia local do Arquivo."
imageWidth: 1512
imageHeight: 805
---

Na tradução, título, resumo e texto mudam. A translationKey permanece igual, mesmo que os nomes dos arquivos sejam diferentes. É assim que relaciono as duas versões. O seletor de idioma encontra a tradução existente; ele não traduz o artigo sozinho. Esse uso da chave segue o front matter do Hugo.

As dimensões precisam corresponder à imagem real. A capa é opcional: uma nota curta pode funcionar melhor só com texto. Para inserir uma imagem no meio de um artigo, uso a sintaxe habitual:

![Descrição do que o diagrama explica](/images/meu-diagrama.webp)

Salvar, visualizar e publicar são etapas diferentes

Durante a escrita, inicio a prévia:

hugo server --buildDrafts --bind 127.0.0.1

O endereço local permite revisar o texto, as imagens e os dois idiomas. --buildDrafts inclui os rascunhos nessa visualização. Salvar o arquivo atualiza a prévia; nada disso coloca o artigo na internet.

Na versão independente, antes de publicar, eu alterava draft para false e verificava o resultado com esta configuração de produção:

python3 -m unittest discover -s tests -v

hugo --config hugo.yaml,hugo.production.yaml \
 --environment production --minify --panicOnWarning \
 --cleanDestinationDir \
 --baseURL https://blog.figueirego.com/

python3 scripts/check-site.py public \
 --production-url https://blog.figueirego.com/

Os testes cobrem comportamentos do projeto; o verificador inspeciona o HTML gerado, links locais, traduções, feeds e metadados de publicação. A configuração de produção também retira as restrições de indexação usadas na prévia. Gerar apenas a versão local e copiar seus arquivos poderia levar essas restrições para o site público.

Testes não substituem leitura. Também preciso conferir se a capa combina com o texto, se a tradução está natural e se os exemplos fazem sentido.

GitHub entrega; Hostinger serve as páginas

Naquela versão, depois da revisão, eu enviava para a main os arquivos de conteúdo e as imagens locais necessárias. O workflow repetia os testes, fazia o build do Hugo e preparava a branch published com o resultado.

O percurso de publicação do blog independente ficou assim:

Markdown e imagens locais
 ↓
GitHub: main
 ↓
testes + Hugo + verificação dos arquivos
 ↓
GitHub: published
 ↓
Hostinger → blog.figueirego.com

O código-fonte fica separado do pacote servido. Não edito published manualmente, porque seu conteúdo é gerado pelo workflow.

Existe um package.json mínimo nessa branch para compatibilidade com o preset da Hostinger. Ele não tem dependências e seu comando de build apenas verifica a existência de public/index.html. O Hugo já executou no GitHub; a hospedagem recebe HTML, CSS, JavaScript e assets prontos. Não preciso manter um servidor de aplicação ou banco de dados próprio para entregar os artigos.

Uma publicação só está confirmada depois de conferir três coisas: os checks no GitHub, o deployment correspondente na Hostinger e a página no domínio público. Um workflow verde comprova aquela execução; não comprova, sozinho, qual versão o leitor recebeu.

As imagens podem seguir junto ou ficar no S3

A AWS entrou como armazenamento de imagens. As páginas continuam na Hostinger. Um arquivo em static/images/ acompanha o build; uma imagem no S3 é enviada separadamente e referenciada por sua URL pública.

Não preciso migrar toda imagem para a AWS para usar o blog. Posso publicar uma capa local junto do artigo e usar o S3 quando quiser manter um arquivo fora do pacote do site. O build não faz uploads automaticamente.

Para o envio, configurei um usuário IAM dedicado, com permissões limitadas ao prefixo de imagens do bucket. Ele usa MFA por passkey e login temporário da AWS CLI, sem uma chave de acesso permanente dentro do projeto. A AWS documenta esse fluxo de autenticação pelo navegador.

O script de upload permite conferir o destino antes de enviar. Os nomes abaixo são exemplos; devem ser substituídos pelos valores de um ambiente já configurado:

aws login --profile meu-blog --region us-east-1

python3 scripts/upload-image.py /caminho/capa.webp \
 --bucket meu-bucket-de-imagens \
 --base-url https://meu-bucket-de-imagens.s3.us-east-1.amazonaws.com \
 --profile meu-blog \
 --prefix images \
 --dry-run

O --dry-run valida o arquivo e mostra um destino possível, mas não envia nada nem confirma acesso público. Para enviar, repito o comando do script sem essa opção. Cada execução gera uma chave nova; a URL da simulação não será a URL final.

Depois do envio, abro a URL retornada sem sessão AWS e verifico a imagem. O script não torna um bucket privado público: a permissão de leitura já precisa estar configurada. No meu fluxo, as imagens publicadas usam HTTPS sem assinatura temporária, para que o endereço não expire junto de uma sessão.

O upload define cache longo com immutable e nomes únicos. Se eu corrigir uma imagem, envio outro arquivo e atualizo a URL no texto. A versão anterior permanece no bucket até ser removida. Também há um alerta de custos: ele avisa sobre o gasto, mas não impõe um teto nem desliga recursos. Blog simples não é promessa de conta zerada.

“Mais lidos” sem consultar estatísticas a cada leitura

O GoatCounter registra as visitas, e o GitHub consulta essas estatísticas durante a publicação e em uma execução diária agendada. O resultado vira uma lista estática incorporada à página inicial.

O token tem permissão de leitura das estatísticas e fica em um secret do GitHub, disponível à etapa responsável por essa consulta. Ele não vai para o JavaScript do leitor. No navegador, há o script público de contagem; a montagem do ranking acontece antes de servir a página. A autenticação da integração segue a API do GoatCounter.

Os filtros têm significados precisos:

Semana: os sete dias completos anteriores à atualização, em UTC.
Mês: os trinta dias completos anteriores à atualização, em UTC.

São janelas móveis, não a semana e o mês do calendário. O dia atual fica de fora por estar incompleto. A lista é atualizada diariamente, sem promessa de tempo real.

As visitas às versões em português e inglês são somadas pela translationKey; o link e o título aparecem no idioma do leitor. O número representa visitas registradas, não uma garantia de leitura completa ou de pessoas únicas entre idiomas. Bloqueadores também podem impedir a coleta.

Se uma consulta falhar, preservo o último resultado válido daquele período, com a data original. Se não houver dados válidos, não invento números: a lista fica vazia, e a seção permanece oculta quando nenhum período tem conteúdo.

A rotina depois de colocar no ar

Comentários ficam no Disqus e precisam de moderação. RSS acompanha as publicações elegíveis de cada idioma e oferece uma forma de seguir o blog. A newsletter ficou de fora por enquanto.

Terceirizar essas funções reduz o que eu opero, mas mantém dependências: hospedagem, armazenamento, comentários e estatísticas podem falhar ou mudar suas condições. O texto e sua publicação continuam apoiados nos arquivos versionados.

Para o próximo artigo, minha rotina é concreta: escrever, revisar a tradução, preparar a capa, conferir a prévia, rodar as verificações, enviar a alteração e abrir a página publicada. Depois, responder aos comentários e corrigir o que precisar. A infraestrutura tem de deixar espaço para esse trabalho.

Nesta série: 1. Arquitetura · 2. Leitura e navegação · 3. Publicação.