De um Blog Simples a um Pequeno Sistema de Publicação

Quando comecei a construir este site, a ideia era, na verdade, bastante simples.

Eu queria um lugar para escrever.

Esse era, mais ou menos, todo o requisito.

Eu queria poder documentar coisas que estava construindo, coisas que estava aprendendo, experimentos, projetos open source e, ocasionalmente, coisas que não tivessem absolutamente nada a ver com software.

Eu não queria começar com um CMS, uma plataforma de publicação complicada ou alguma arquitetura elaborada de gerenciamento de conteúdo.

Eu só queria escrever um artigo, colocá-lo em algum lugar dentro do projeto e fazer com que o site o renderizasse.

Então comecei com MDX.

Na época, eu não sabia muito sobre MDX. Markdown eu conhecia, obviamente, mas MDX era algo com que eu ainda não tinha trabalhado de verdade.

Acabou sendo um formato muito mais interessante do que eu esperava inicialmente.

Começando com Markdown

A primeira versão do sistema de conteúdo era intencionalmente simples.

Um artigo era, essencialmente, um arquivo contendo frontmatter e Markdown:

---
title: "Meu Artigo"
description: "Algo sobre o qual eu queria escrever."
date: "2026-08-17"
tags:
  - Engenharia
---

# Meu Artigo

Alguns pensamentos aqui.

A aplicação podia ler o arquivo, extrair os metadados e renderizar o conteúdo.

Era suficiente.

E, por algum tempo, eu realmente não precisava de mais nada.

Mas é normalmente aí que esses projetos começam a ficar interessantes.

Você resolve o problema original e então começa a usar aquilo que construiu.

E, quando comecei a escrever de verdade, comecei a perceber coisas que queria melhorar.

MDX foi a primeira surpresa

Uma das primeiras coisas que descobri foi o MDXComponents.

Eu nunca tinha pensado muito sobre Markdown como algo que pudesse ter uma camada de renderização por trás.

Eu estava acostumado a pensar em Markdown como conteúdo.

O MDX mudou essa perspectiva.

Em vez de tratar cada elemento como algo que o renderizador de Markdown simplesmente produz, eu podia decidir como determinados elementos deveriam se comportar dentro da aplicação.

Links poderiam ter seu próprio comportamento.

Imagens poderiam ter sua própria implementação.

Blockquotes poderiam ser estilizados de maneira consistente.

E blocos de código poderiam se tornar algo muito mais interessante do que simplesmente um elemento <pre>.

A estrutura começou a ficar mais ou menos assim:

MDX
 │
 ├── headings
 ├── paragraphs
 ├── links
 ├── images
 ├── blockquotes
 │
 └── code
       ↓
 MDXComponents
       ↓
   CodeBlock

Esse foi um daqueles momentos em que o projeto deixou de ser apenas uma coleção de arquivos Markdown.

Agora havia um pequeno sistema de renderização por trás do conteúdo.

Então eu quis blocos de código melhores

Isso provavelmente era inevitável.

Se vou escrever sobre software, vou ter código nos artigos.

E blocos de código simples eram funcionais, mas não pareciam realmente algo que eu gostaria de publicar.

Então comecei a pesquisar sobre syntax highlighting e acabei usando Shiki.

Isso deu aos blocos de código uma camada apropriada de syntax highlighting, enquanto ainda me permitia manter o código-fonte dentro do próprio documento MDX.

Mas, novamente, uma funcionalidade levou a outra.

Depois de ter syntax highlighting, eu quis nomes de arquivos.

Então quis um botão para copiar o código.

Depois quis destacar linhas específicas.

Depois quis passar metadados através do próprio Markdown.

Isso acabou levando ao plugin remarkCodeMeta e a um componente CodeBlock personalizado.

Algo tão simples quanto:

const gradient = DynamicGradient.init("#hero", {
  type: "linear",
  colors: ["#ff7e5f", "#feb47b"],
});

agora poderia carregar informações que o sistema de renderização poderia utilizar.

Essa foi uma parte que achei particularmente interessante.

O próprio artigo poderia descrever como aquele código deveria ser apresentado sem que eu precisasse construir manualmente um componente React toda vez que quisesse mostrar alguma coisa.

O conteúdo começava a carregar não apenas a informação que estava sendo apresentada, mas também parte das informações sobre como ela deveria ser apresentada.

Essa distinção se tornou importante mais tarde.

Então o escopo começou a crescer

Essa provavelmente é a parte mais previsível de todo o projeto.

O site começou como:

Eu quero um lugar para escrever.

Depois se tornou:

Eu quero um lugar confortável para escrever.

Então:

Eu quero que os artigos tenham uma aparência boa.

Depois:

Eu quero que os exemplos de código tenham uma aparência boa.

E, eventualmente:

Eu quero poder publicar sem precisar criar arquivos manualmente dentro do repositório.

Essa última mudança alterou bastante a direção do projeto.

Porque, tecnicamente, o sistema já funcionava.

Eu podia criar um arquivo .mdx, fazer commit, publicar a aplicação e um novo artigo estaria disponível.

Mas havia algo um pouco estranho nesse fluxo.

Se o objetivo do projeto era me dar um lugar para escrever, por que escrever algo novo exigia que eu entrasse no código?

O conteúdo estava sendo tratado como parte do código-fonte da aplicação.

Isso não era necessariamente errado.

Para um blog de desenvolvedor, na verdade, faz bastante sentido.

Mas comecei a me perguntar se seria possível manter a simplicidade do sistema baseado em MDX e, eventualmente, me dar uma interface própria para criar e gerenciar o conteúdo.

Eu não queria resolver isso imediatamente com um CMS.

Queria descobrir até onde conseguiria levar o sistema que já havia construído.

E esse se tornou o próximo problema a ser resolvido.

Então veio o português

Havia outro requisito que eu não tinha planejado inicialmente.

Eu estava escrevendo tudo em inglês.

Mas queria que o site funcionasse adequadamente em português também.

E não queria que o português parecesse uma versão secundária do site.

A solução óbvia seria recorrer a alguma solução existente de internacionalização.

Em vez disso, decidi tornar a localização parte do próprio modelo de conteúdo.

A estrutura acabou ficando assim:

content/
├── blog/
│   └── building-dynamic-gradient/
│       ├── en.mdx
│       └── pt.mdx
│
└── notes/
    └── hello-world/
        ├── en.mdx
        └── pt.mdx

Agora o idioma não era apenas algo que a interface precisava conhecer.

Ele se tornou parte do conteúdo.

Essa decisão afetou muito mais do que os próprios artigos.

Isso significou pensar em:

• rotas conscientes do idioma
• troca de idioma
• metadados
• breadcrumbs
• geração estática
• busca de posts
• RSS
• navegação

Um requisito que inicialmente parecia ser apenas:

"Quero uma versão em inglês e outra em português."

acabou influenciando praticamente toda a aplicação.

E esse foi outro exemplo da arquitetura surgindo a partir dos requisitos, em vez de ser projetada isoladamente antes deles existirem.

O projeto continua me ensinando o que precisa

Essa provavelmente é a parte que mais gostei em construir o site.

Nenhuma dessas coisas fazia parte de algum enorme plano de arquitetura que eu tinha desde o começo.

Eu não sentei para projetar um sistema de publicação.

Eu queria um blog.

Então quis uma renderização de conteúdo melhor.

Depois blocos de código melhores.

Depois localização.

Depois um fluxo de publicação melhor.

E cada requisito expôs outro pequeno problema que valia a pena resolver.

A arquitetura foi crescendo a partir desses requisitos, em vez de tentar prever todos eles antecipadamente.

Acho que essa é uma coisa que tenho apreciado cada vez mais no desenvolvimento de software.

Às vezes, a melhor arquitetura não é aquela que você consegue imaginar antes de escrever a primeira linha de código.

Às vezes, é aquela que emerge depois que você realmente usa aquilo que está construindo.

Existe uma diferença entre projetar para requisitos hipotéticos e projetar em resposta a requisitos reais.

O primeiro pode produzir diagramas impressionantes.

O segundo tende a produzir software que realmente reflete aquilo que o sistema precisa.

E agora estou construindo aquilo que constrói aquilo

A parte engraçada é que eu ainda não terminei.

O próximo passo provavelmente é o mais interessante.

Quero poder fazer login no próprio site e criar um post diretamente por ele.

Adicionar o título.

Escrever o conteúdo.

Adicionar imagens e links.

Escolher se é um artigo ou uma nota.

Selecionar o idioma.

Visualizar.

Publicar.

E, idealmente, nunca mais precisar abrir o repositório apenas para fazer um artigo existir.

O que significa que o projeto que começou como:

"Eu preciso de um lugar para escrever."

está lentamente se tornando um pequeno sistema de publicação.

E suponho que exista algo apropriadamente recursivo nisso.

Comecei a construir este site porque queria um lugar para escrever. Agora estou construindo as ferramentas que tornam mais fácil para eu escrever.

E, naturalmente, estou escrevendo sobre a construção dessas ferramentas.