Figueirego Blog – Next.js

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

Mon, 19 Oct 2026 04:15:50 -0300

Salvar um artigo no editor não significa que ele está publicado. O texto ainda precisa ser revisado, gerar uma página, passar pelas verificações e chegar à hospedagem. Depois disso, preciso abrir o endereço público e conferir o que o leitor recebeu.

Essa distinção ficou importante ao integrar blog e portfólio. Na primeira versão, o blog tinha um fluxo separado. Hoje, as duas partes saem do mesmo repositório e são entregues pela aplicação Next.js na Hostinger. O subdomínio antigo deixou de ser o destino.

O artigo começa com texto e metadados

Escrevo em Markdown. Antes do corpo, um bloco de dados chamado front matter informa como o artigo deve ser apresentado. Este é um exemplo reduzido, não um arquivo pronto para publicar:

---
title: "Como organizei meu blog"
date: 2026-10-19T09:00:00-03:00
draft: true
author: "Matheus Figueirêdo"
translationKey: how-i-organized-my-blog
description: "As decisões para organizar conteúdo, navegação e publicação."
tags: ["Hugo", "publicação"]
---

A data precisa corresponder à publicação real. draft: true mantém o texto fora do build público. Na tradução, o título, a descrição, os temas e o corpo mudam; a translationKey continua igual.

Uma capa pode ser acrescentada depois. Quando existe, precisa de URL, descrição alternativa e dimensões correspondentes ao arquivo. O artigo deve continuar legível sem depender da imagem para informar seu assunto.

Duas prévias para perguntas diferentes

Para revisar apenas os textos, posso usar o servidor do Hugo. Estes comandos partem da raiz do repositório e pressupõem Hugo extended na versão fixada pelo projeto:

cd blog
hugo server --buildDrafts --bind 127.0.0.1

A opção inclui rascunhos na prévia local. É útil para conferir texto, sumário e tradução. Para avaliar a integração com o portfólio, uso o projeto completo, em outro terminal:

cd client
npm ci
npm run dev

Esse caminho pressupõe Node.js 24.12.0 ou superior e Hugo extended 0.167.0 no ambiente. O script de desenvolvimento monta o blog no início. Depois de editar Markdown, preciso reconstruir essa parte com node scripts/build-blog.mjs --preview e recarregar a página. Ele não substitui o acompanhamento de arquivos do servidor Hugo dedicado, e o build integrado normal continua excluindo rascunhos.

Os comandos dependem dos auxiliares deste repositório privado. Para outro projeto, a ideia reproduzível é manter uma prévia rápida do conteúdo e outra que exercite a integração completa.

A versão que passa pelos testes é a que segue adiante

O fluxo atual é:

arquivos revisados → dev → main
 ↓
 testes e build integrado
 ↓
 SHA aprovado → production
 ↓
 Hostinger
 ↓
 conferência do site público

SHA é o identificador de um commit. Usá-lo na promoção permite relacionar a versão testada à versão enviada para publicação. A CI não deve aprovar um commit e promover silenciosamente outro que chegou depois.

O comando central de verificação, executado em client/, é:

node scripts/verify-release.mjs --production

Ele reúne checagem de tipos, lint, formatação, testes, build Next.js com Hugo e verificação dos arquivos gerados. Para conhecer as etapas sem executá-las, uso --dry-run. Nenhuma dessas opções, sozinha, envia código ao GitHub.

Depois dos checks da main, a automação promove o commit aprovado para production. A Hostinger acompanha essa branch. Se a main avançou durante a execução, a versão nova precisa passar por sua própria verificação. A promoção não deve atropelar o histórico com um envio forçado.

Revisar, testar, publicar e conferir: as quatro etapas do fluxo de entrega deste site.

Abrir diagrama em tamanho original

Conferir três resultados separados

Um check verde mostra o resultado da verificação. O deployment na Hostinger informa se a hospedagem conseguiu construir e iniciar a versão correspondente. Abrir as páginas públicas mostra o que está sendo entregue.

Por isso, a conferência inclui os dois idiomas, os links do artigo, as imagens, o RSS e o caminho de volta ao restante do site. Também preciso olhar o SHA da implantação. Um código de resposta HTTP 200 não demonstra que todos os componentes da página funcionaram.

Para conteúdo, há uma verificação adicional: confirmar que um rascunho não entrou na busca, no sitemap ou no feed. Uma prévia que inclui rascunhos não pode ser copiada para produção como se fosse o build público.

Recorte real do deploy concluído em 19/10/2026, referente à publicação inicial desta série com as capas. A hospedagem identifica o commit que recebeu.

Ver captura em tamanho original

Os mais lidos também passam por publicação

O GoatCounter fornece estatísticas de visitas. Uma rotina no GitHub consulta esses dados e grava um snapshot em blog/data/popular.json. O build incorpora esse resultado e entrega um arquivo público em /blog/popular.json.

O navegador pode atualizar as listas a partir desse arquivo, sem receber o token de consulta ao GoatCounter. A rotina de coleta tem execução diária e tentativas de recuperação. Horários agendados dependem dos provedores; não são uma garantia de atualização no segundo marcado.

Semana e mês representam os sete e trinta dias completos anteriores, em UTC. As versões de um mesmo artigo são agregadas pela identidade editorial. Isso conta visitas registradas, não pessoas únicas entre idiomas nem prova de leitura completa.

Quando a coleta falha, o fluxo conserva o snapshot anterior em vez de publicar números inventados. Uma atualização válida ainda precisa passar pela verificação e chegar à hospedagem. Monitorar o JSON público ajuda a detectar a diferença entre ter coletado dados e ter publicado esses dados.

Essa rotina faz parte do custo de manter o site. Automatizar ajuda, mas o resultado importante continua sendo o conteúdo correto no endereço que a pessoa abre.

Construindo meu blog, parte 1: da landing page ao site

Mon, 19 Oct 2026 04:15:50 -0300

Eu já tinha um projeto de site. Era uma landing page, com uma ideia que eu ainda queria manter, mas que precisava de mais espaço. Resolvi reaproveitar essa base, subdividir o conteúdo e melhorar a forma de apresentar meu trabalho e as coisas sobre as quais queria escrever.

Uma das mudanças mais visíveis foi transformar uma experiência de terminal em um desktop. O terminal tinha uma linguagem muito voltada para quem programa. Eu queria que uma pessoa pudesse explorar o site sem precisar conhecer comandos. Janelas e ícones me pareceram um ponto de partida mais familiar, embora isso ainda precisasse funcionar bem na prática e no celular.

O blog entrou nessa mesma construção. Meu receio ao juntar os dois era confundir a navegação e não conseguir ser claro sobre o que cada área oferecia. Por isso, esta série começa pela organização do projeto. O código veio acompanhado de decisões sobre comunicação.

O desktop real do portfólio: janelas e pastas como alternativa de exploração, mantendo a navegação convencional disponível.

Ver captura em tamanho original

Referências com papéis diferentes

O blog do Akita me ajudou com a construção do blog e com ideias para a rotina de publicação. Já o site do Zeno Rocha foi uma referência de apresentação: como mostrar o próprio trabalho e deixar a exploração intuitiva.

Usei essas referências para estudar o que poderia melhorar, reaproveitar ou descartar. Eu tinha uma ideia própria para preservar e precisava entender quais soluções ajudavam a expressá-la. A parte mais trabalhosa acabou sendo acertar o design para transmitir essa identidade.

As IAs participaram desse estudo. Concentrei mais no Codex a busca de informação e a investigação do projeto; usei Claude e Antigravity principalmente no design. Depois voltei ao Codex com skills para separar e aprofundar cada conceito. Essa divisão descreve meu processo, não uma regra sobre qual ferramenta qualquer pessoa deveria usar.

Onde termina o site e começa o blog

Hoje, o portfólio usa Next.js, React e TypeScript. Os artigos ficam em Markdown e são gerados pelo Hugo. O Hextra serve como base do tema, com personalizações em arquivos do projeto.

O Hugo é um gerador: lê o texto e seus metadados e produz HTML, CSS, JavaScript e índices. O Next.js reúne esse resultado com as páginas do portfólio. A Hostinger executa a aplicação Next.js e entrega o conjunto no mesmo domínio.

blog/content/ → Hugo → páginas, busca e feeds do blog
 ↓
 client/public/blog/
 client/public/pt/blog/
 ↓
 Next.js + páginas do portfólio → Hostinger

Isso corrige uma descrição da primeira versão do projeto, quando o blog estava separado. O conjunto atual tem um servidor Next.js em produção; o Hugo só roda na geração dos arquivos. Os artigos não precisam de uma API própria de edição ou de um banco de dados para montar seu conteúdo a cada visita.

Markdown passa pelo Hugo; arquivos gerados são integrados ao Next.js e entregues pela Hostinger.

Abrir diagrama em tamanho original

Cada tecnologia precisa ter um trabalho claro

Componente	Responsabilidade neste projeto
Markdown	Texto, resumo, data, idioma e demais dados editoriais.
Hugo e Hextra	Geração do blog e base dos layouts.
Next.js	Páginas do portfólio e entrega integrada do site.
GitHub e Actions	Histórico do código e conteúdo, testes e preparação da publicação.
Hostinger	Build e execução da versão publicada.
Amazon S3	Armazenamento das imagens enviadas separadamente.
Disqus	Conversas e moderação dos comentários.
GoatCounter	Estatísticas de visitas que alimentam os mais lidos.

Não acrescentei um banco de dados só para guardar os artigos. Também não coloquei o armazenamento das imagens dentro da responsabilidade do Hugo. Essa separação ajuda a encontrar problemas: uma imagem indisponível, um artigo ausente e um comentário que não carrega podem ter causas diferentes.

Organização que dá para enxergar nos arquivos

A estrutura principal ficou assim:

client/ aplicação Next.js
blog/content/pt/ conteúdo em português
blog/content/en/ conteúdo em inglês
blog/layouts/ personalizações de layout
blog/assets/ estilos e interações
blog/themes/hextra/ tema de base
blog/scripts/ auxiliares de publicação e imagens
.github/workflows/ verificações e automações do conjunto

As personalizações ficam fora da pasta do tema. Isso facilita revisar uma atualização sem misturar cada ajuste local ao código original do Hextra. Continua sendo necessário testar a atualização; a estrutura de pastas não garante compatibilidade.

O repositório ativo é privado. O resultado publicado, incluindo artigos, imagens e scripts enviados ao navegador, é público. O leitor não precisa acessar o repositório para usar o site, mas os comandos desta série são exemplos do meu projeto, não um pacote público pronto para clonar.

O que eu organizaria antes de começar

Se começasse hoje, olharia melhor para o design e a arquitetura antes de implementar. Separaria cada responsabilidade, o propósito de cada área e o papel das tecnologias. Fui descobrindo parte dessa organização enquanto construía.

Para um projeto parecido, eu começaria escrevendo o caminho do visitante: onde ele entende quem sou, onde encontra meus projetos e onde lê os textos. Depois desenharia o percurso de um artigo até a publicação. Esses dois mapas ajudam a perceber quais partes precisam conversar e quais podem continuar independentes.

Na próxima parte, entro no ponto que mais exigiu tentativas: fazer essa organização aparecer na interface, sem obrigar quem chega a entender a arquitetura do projeto.