Migrar um site antigo de um gerador de sites estáticos para outro não é apenas trocar um comando de build. Conteúdo, URLs, templates, versões em outros idiomas, publicação e expectativas dos leitores são coisas que deve ser levadas em consideração.
Este artigo fala sobre a migração deste site de Jekyll para Hugo, descreve os commits de setembro de 2026 que registraram o trabalho e transforma a experiência em um processo que qualquer pessoa pode repetir, com ou sem um assistente de IA.
A migração neste repositório
O ponto de partida era um site Jekyll com anos de publicações em português e um histórico de URLs já estabelecido. O objetivo era substituir Jekyll por Hugo, preservar o arquivo, acrescentar traduções em inglês, usar inglês como idioma padrão e manter o português disponível sob /pt/.
Em 27 de setembro, o commit inicial da migração, 36a8a64, substituiu o projeto Jekyll por um site Hugo bilíngue. A mensagem do commit registra a migração do arquivo em português, a criação das traduções em inglês, a navegação localizada e um fluxo inicial de publicação no GitHub Pages. A configuração e a estrutura de tema do Jekyll deram lugar à configuração, aos layouts, ao conteúdo e aos arquivos estáticos do Hugo.
Em seguida, o plano de publicação mudou. O commit 7500f13 excluiu do controle de versão o arquivo de bloqueio gerado pelo Hugo, e 9a6d8c5 ajustou as permissões do fluxo inicial do Pages. Quando o Cloudflare Pages se tornou o destino de publicação, cb749dc definiu o domínio canônico como kindofidea.com e removeu o fluxo do GitHub Pages, que já não seria usado.
Os commits seguintes completaram o site: ca2c99a atualizou a identidade visual e as fontes de Kind of Idea; 0f5833e acrescentou os perfis do autor; e 7a780f4 e 4072f88 localizaram as URLs das publicações e das páginas estáticas. A translationKey compartilhada conecta cada página em inglês à sua versão em português, enquanto cada idioma conserva seu próprio slug.
Também houve documentação e refinamentos: 6b1c0c3 e badbaf4 documentaram o fluxo de publicação bilíngue e os comandos do Hugo; a28e14c melhorou a largura de leitura dos artigos; b19fbd5 criou o favicon com um K manuscrito azul-marinho; e, em 28 de setembro, 59caac3 acrescentou instruções para configurar o Cloudflare Pages do zero. Esses commits mostram que uma migração é uma sequência: primeiro transferir o conteúdo, depois tornar rotas, publicação e experiência de leitura confiáveis.
Uma migração reproduzível, passo a passo
1. Faça um inventário antes de alterar arquivos
Leia a configuração do Jekyll, os layouts, includes, plugins, arquivos estáticos, rascunhos e algumas publicações representativas. Anote o domínio atual, as regras de permalink, feeds, taxonomias e integrações importantes. Faça um backup e comece em um branch Git limpo para poder recuperar o site original.
Não presuma que todo arquivo Markdown seja intercambiável. Tags Liquid e variáveis de template do Jekyll podem precisar ser convertidas em shortcodes ou templates Go do Hugo. Identifique esses casos antes de fazer uma conversão em massa.
2. Defina o conteúdo e as URLs
Escolha o idioma padrão e o formato das URLs de cada idioma antes de migrar as publicações. Neste site, o inglês usa o domínio raiz e o português usa /pt/. Os arquivos e slugs de cada tradução podem ser localizados, mas o par deve compartilhar uma chave:
slug: "de-jekyll-para-hugo-migracao-bilingue-passo-a-passo"
translationKey: "from-jekyll-to-hugo-bilingual-site-migration"
No arquivo em inglês, use a mesma translationKey e um slug em inglês, por exemplo from-jekyll-to-hugo-bilingual-site-migration. Assim, o seletor de idiomas conecta as páginas sem obrigar os dois endereços a usarem o mesmo idioma.
3. Configure o Hugo e migre em lotes pequenos
Instale o Hugo, crie ou atualize o hugo.toml e configure o endereço-base, os idiomas, as taxonomias e os permalinks. Migre primeiro uma publicação representativa. Confira se data, título, slug, categorias, tags, imagens e links foram preservados antes de converter o restante do arquivo.
Mantenha os arquivos originais ou um backup até revisar o site gerado. Converta conscientemente os recursos específicos dos templates Jekyll, em vez de copiar Liquid para os layouts do Hugo. Em arquivos grandes, automatize alterações repetitivas no front matter, mas confira os resultados e revise manualmente os casos especiais.
4. Adicione traduções e páginas localizadas
Use o comando de conteúdo do Hugo para criar um par de publicações:
hugo new content/posts/2026-09-28-from-jekyll-to-hugo-bilingual-site-migration.en.md
hugo new content/posts/2026-09-28-de-jekyll-para-hugo-migracao-bilingue-passo-a-passo.pt.md
Escreva cada artigo em seu próprio idioma. Mantenha a translationKey idêntica e localize o título, o texto e o slug. Use a mesma abordagem para páginas estáticas como Sobre, Histórico e Tópicos. Confira se o seletor de idiomas leva à tradução correspondente, e não simplesmente à página inicial.
5. Compile e inspecione o resultado real
Execute a prévia local e o build de produção:
hugo server
hugo --minify
Confira os dois idiomas, publicações antigas e novas, páginas de categorias e tags, navegação, imagens, feeds e a página 404. Inspecione os arquivos gerados em public/ e verifique se URLs antigas importantes continuam funcionando ou têm um redirecionamento intencional. Um build bem-sucedido é necessário, mas não prova sozinho que todas as rotas e traduções estão corretas.
6. Configure a publicação depois de validar
No Cloudflare Pages, conecte o repositório do GitHub, escolha o branch de produção e configure o comando de build do Hugo e o diretório public como saída. Este projeto usa o branch master, a raiz do repositório / e hugo --minify. Adicione um domínio personalizado nas configurações do Pages, siga as instruções de DNS e certificado e, depois da publicação, confira HTTPS e as rotas nos dois idiomas.
Se não tiver certeza sobre as configurações de publicação, envie primeiro uma alteração pequena e revisada. Confira os logs do Pages e o site publicado antes de remover a hospedagem antiga. Nunca coloque credenciais ou tokens de API no repositório.
Onde a IA ajuda e onde não substitui você
Essa migração foi realizada com o auxílio de um assistente de IA usando Copilot SDK no VS Code. O papel do agente no processo foi inspecionar o projeto existente, ajudar a transformar conteúdo e templates, implementar as mudanças bilíngues e de publicação solicitadas e executar verificações de build e rotas. Os commits registram publicamente o trabalho resultante; isso não significa que uma IA substitua a revisão ou a responsabilidade pelo site.
Um fluxo útil com IA continua sendo conversacional, mas também orientado por testes:
- Peça ao assistente para inventariar o projeto e relatar tipos de conteúdo, regras de URL, templates e riscos antes de editar.
- Defina o idioma e o formato das URLs de destino e migre uma amostra pequena antes de pedir uma conversão em massa.
- Solicite alterações específicas, em lotes fáceis de revisar. Preserve datas e metadados e confira as traduções em vez de aceitar o texto gerado sem revisão.
- Execute os builds do Hugo e inspecione URLs geradas, links de idioma e páginas representativas. Corrija falhas específicas e repita as verificações.
- Revise o diff, faça commit somente dos arquivos planejados, publique quando estiver tudo pronto e confira o deploy real no Cloudflare.
O mesmo roteiro funciona sem IA: inspecionar, planejar, migrar, compilar, revisar e publicar. A IA pode reduzir tarefas repetitivas e ajudar a explicar templates desconhecidos, mas cabe à pessoa decidir o comportamento do site, conferir o conteúdo e as URLs, proteger as credenciais e escolher quando a mudança está pronta para publicação.