Migrando do WordPress para o Quarkus Roq

Recentemente migrei este blog do WordPress para o Quarkus Roq. A mudança não foi motivada por hype nem por novidade. Ela foi motivada pelo fato de que o WordPress é um sistema muito grande e complexo para o que eu realmente preciso aqui: algumas páginas estáticas e um blog.

Para quem mantém uma plataforma de publicação com muito conteúdo e vários usuários, o WordPress ainda faz sentido. Mas, para o meu caso de uso, ele passou a representar superfície demais para manter, software demais para proteger e complexidade demais em torno de um site que é basicamente texto.

O Roq pareceu uma escolha melhor por três razões simples:

Eu já conheço bem o ecossistema Quarkus.
Arquivos em Markdown são muito mais fáceis de integrar ao meu fluxo mental e ao meu wiki pessoal.
Um site estático é significativamente mais simples de manter do que uma instalação completa do WordPress.

A migração em si acabou acontecendo em duas fases. A primeira foi sobre mover o conteúdo. A segunda foi sobre transformar esse conteúdo convertido em um site que realmente se comportasse como um site pronto.

Também vale mencionar que eu não entrei nisso completamente no escuro. Recebi várias dicas úteis e bastante confiança ao ler o post da Zineb Bendhiba, From Jekyll to Quarkus Roq: Migrating My Blog as a Java Dev. O relato dela parte de uma situação diferente, mas ajudou a confirmar algumas coisas práticas com antecedência: Roq é uma opção viável para um blog já existente, preservar URLs antigas importa, e vale a pena pensar cedo no quanto do tema padrão você quer manter e no quanto quer assumir por conta própria.

O primeiro requisito: um dump do banco de dados do WordPress

Um pré-requisito importante não apareceu com clareza suficiente nos logs da migração, mas deveria ter aparecido: antes de qualquer outra coisa, você precisa de um dump do banco de dados do WordPress.

Esse dump foi a verdadeira fonte de verdade da migração. Foi ele que permitiu extrair:

posts publicados
datas de publicação
tags e categorias
slugs originais
estrutura antiga de permalinks
referências a mídias hospedadas em wp-content/uploads

Sem esse dump SQL, essa migração teria sido puro chute.

Fase 1: convertendo o conteúdo

A primeira etapa foi relativamente mecânica, mas ainda assim não trivial.

Os posts foram extraídos dos dados do WordPress, convertidos para Markdown e gravados na estrutura de conteúdo do Roq:

content/posts/YYYY-MM-DD-slug/index.md

Essa parte também exigiu preservar metadados como título, data de publicação, tags e descrições. Na prática, foi nesse ponto que o site deixou de ser "um banco de dados do WordPress" e passou a ser uma árvore normal de arquivos que pode ser editada com ferramentas comuns.

Só essa mudança já é um dos maiores benefícios da migração para mim. Quando os posts passam a ser apenas arquivos Markdown em um repositório, fica muito mais fácil pesquisar, criar links, editar, fazer backup, refatorar e reutilizar o conteúdo.

Houve também um detalhe no nível do conteúdo que precisou de atenção: trechos de código.

No Roq, dependendo do que você está escrevendo, alguns trechos precisam ser escapados para serem renderizados corretamente em vez de serem interpretados no caminho. Eu tinha alguns posts usando expressões de propriedades no estilo do Maven, e eles precisaram ser ajustados para $\{camel.version}.

É um detalhe pequeno, mas é exatamente o tipo de coisa que mostra por que uma migração ainda exige revisão cuidadosa mesmo depois que a conversão em massa aparentemente terminou.

Mídia também faz parte da migração

Mover o corpo dos posts foi só parte do trabalho. Muito conteúdo também dependia de imagens e arquivos antes hospedados pelo WordPress em https://www.orpiske.net/wp-content/uploads/.

Isso significou que a migração também precisou:

identificar mídias referenciadas pelos posts
baixar os arquivos que ainda estavam disponíveis
reescrever links para caminhos locais dentro da árvore de conteúdo do Roq
registrar tudo o que estivesse faltando para acompanhamento manual

É fácil subestimar essa parte. Se você migrar só o texto e esquecer os assets, o resultado parece bem-sucedido no repositório, mas quebrado no navegador.

Fase 2: transformando isso em um site de verdade

A segunda fase foi mais interessante do que eu esperava. Converter o conteúdo não bastava. Assim que os posts ficaram no lugar, outros problemas ficaram evidentes.

O principal trabalho complementar foi:

definir uma direção de tema personalizada
melhorar a legibilidade com conteúdo real na tela
fazer o deploy funcionar corretamente sob um subcaminho
adicionar RSS e endpoints de feed
preservar os permalinks antigos do WordPress
restaurar páginas de tags funcionais

Tema e legibilidade

Eu queria que o resultado fosse minimalista, limpo e moderno, mas ainda simples e amigável a padrões.

Isso levou a um layout centrado em tipografia, com fluxo de leitura em coluna única, HTML semântico e estilo contido. Quando artigos reais foram renderizados, alguns problemas ficaram visíveis imediatamente: links inline estavam discretos demais, o texto do corpo estava leve demais e a hierarquia dos títulos estava mais fraca do que deveria. Esse é o tipo de coisa que você só percebe de verdade depois que os dados da migração chegam à página.

Testes de deploy sob um subcaminho

Um ponto prático foi testar o site em:

https://orpiske.net/new-website/

Esse não seria o caminho público final. Era apenas um teste temporário no servidor para garantir que o site continuaria com a aparência correta depois do deploy.

Mesmo como teste, isso expôs a armadilha clássica dos sites estáticos: se seus caminhos presumem que o site está hospedado na raiz do domínio, as coisas quebram muito rápido. CSS, navegação e URLs geradas precisam concordar com o caminho real de deploy que você está validando.

Feeds e tags

O suporte a RSS e feeds precisou ser ligado explicitamente, e as tags também deram trabalho extra. Nos logs, uma das lições mais úteis foi perceber que algo pode até ser gerado tecnicamente e ainda assim não estar de fato integrado. Um arquivo de feed que existe, mas não está linkado, continua efetivamente ausente.

Com as tags aconteceu algo parecido. Os links de tags existiam, mas o suporte adequado ainda não estava totalmente habilitado no começo, e, quando foi habilitado, as páginas resultantes não combinavam visualmente com o restante do site. Resolvi isso de forma pragmática, em vez de tentar forçar imediatamente uma personalização profunda perfeita.

Preservando URLs antigas do WordPress

Isso era inegociável.

Um blog estabelecido acumula links ao longo do tempo, e uma migração que quebra esses links não está terminada. O dump do WordPress tornou possível mapear os permalinks antigos para a nova estrutura do Roq e adicionar aliases para que URLs legadas continuassem funcionando.

Isso não foi perfeitamente mecânico em todos os casos. Alguns posts exigiram julgamento porque datas ou títulos haviam mudado ao longo do tempo. É mais um lembrete de que migrações raramente são tão limpas quanto a história de um export/import em etapa única faz parecer.

Por que isso combina mais comigo

Depois de passar por todo o processo, estou ainda mais convencido de que essa foi a decisão certa.

Com o Roq, o site fica mais próximo da forma como eu realmente trabalho:

conteúdo em texto puro
mudanças versionadas em Git
ferramentas que eu já conheço
resultado final estático
manutenção bem menor em escopo

Mais importante: eu não preciso mais operar um CMS completo só para publicar notas, artigos e algumas páginas fixas. Para as minhas necessidades, isso é um compromisso muito melhor.

Consideração final

A migração do WordPress para o Quarkus Roq não foi apenas uma exportação de conteúdo. Foi uma redução de complexidade.

O dump do banco tornou a mudança possível, o Markdown tornou o conteúdo administrável de novo, e a segunda passada da migração tornou o resultado utilizável como um site de verdade.

Se o seu site é majoritariamente conteúdo e você já se sente confortável no ecossistema Quarkus, o Roq é uma alternativa muito interessante.