Como mencionei em minha postagem no início desta semana, acabamos de concluir a migração do WordPress para o Jekyll. Descrevi alguns motivos para isso, mas basicamente me resumi à preferência, velocidade e capacidade de fazer alterações facilmente.
Estruturas como Jekyll (ou Astro) não são para todos, embora façam muito mais sentido no ambiente geral de proliferação de IA, com o markdown se tornando a língua franca dos LLMs e uma tendência geral para sites sem cabeça. Todo mundo sabe o quão inseguro o WordPress pode ser, embora isso seja amplamente mitigado ao trabalhar com um host confiável.
O maior problema era a velocidade. Como uma empresa de plataforma, avançamos muito rápido e sempre nos sentimos limitados pelo que poderíamos fazer com o WordPress e éramos constantemente prejudicados pela existência ou não de desenvolvedores WP disponíveis. Mas é difícil encontrar bons desenvolvedores para qualquer framework e principalmente para WordPress. Quando você encontra alguém que é bom em desenvolvimento em WordPress, significa que ele é bom em praticamente tudo o que tenta e, portanto, parece um desperdício de talento fazê-lo trabalhar em WordPress. É como uma fuga de cérebros embutida.
Desde o advento de agentes de codificação como Claude Code, tornou-se mais fácil contornar completamente esse problema simplesmente migrando para outra plataforma. Escolhemos Jekyll pelos motivos que discutirei na próxima seção.
Decisões de arquitetura que levaram ao Jekyll
Na semana passada, Cloudflare anunciou uma nova estrutura de CMS que eles apelidaram de “sucessor espiritual” do WordPress. É baseado no Astro, que é um dos geradores de sites estáticos (SSG) mais populares do momento. Parece ótimo, mas queríamos algo com o qual tivéssemos experiência e que fosse uma estrutura madura. Como mencionei em meu post anterior, nosso site rodava em Jekyll há muito tempo, então o conhecíamos bem.
Para quem não conhece: a maior diferença entre um CMS como o WordPress e um SSG é que neste último não existe banco de dados (normalmente), nem mesmo servidor de aplicação. Você está trabalhando inteiramente em modelos HTML, inclusões, arquivos de layout, arquivos de configuração e, em seguida, descontos para todo o resto.
Os metadados na página são definidos como frontmatter, que são os dados YAML entre o --- delimitadores na parte superior do arquivo markdown.
Então, por exemplo, o frontmatter desta postagem é assim:
layout: post
title: "Moving from WordPress to Jekyll (and static site generators in general)"
description: "Some technical notes on how and why we moved from WordPress to Jekyll, a well-known static site generator (SSG)."
date: 2026-04-09
author: Ray Grieselhuber
permalink: /blog/rebuilding-demandsphere-with-jekyll-and-claude-code/
tags:
- Engineering
- AI Search
Fora isso, essas postagens são apenas descontos diretos. Nós os iniciamos no _drafts pasta e mova-os para a _posts pasta quando estivermos prontos para publicar.
Migrando 288 postagens de blog WordPress e outras páginas
A área que mais demorou, além do design, foi a migração adequada do conteúdo existente. O site em si tem mais de 15 anos de postagens, mas, francamente, não precisávamos de todas elas.
Portanto, usamos nossas ferramentas GSC no DemandSphere para identificar as páginas que realmente tinham patrimônio valioso e usamos dados de indexação para decidir quais páginas poderiam ser deixadas sem indexação – e simplesmente excluídas – como parte da migração.
O WordPress tem uma exportação XML que você pode usar para exportar tudo, então começamos com isso. Felizmente, consegui aproveitar bastante o Claude Code para analisar cada página em termos de patrimônio que ela possuía e filtrar rapidamente o que não precisávamos.
Demorou um pouco mais para que as imagens em destaque (e as imagens em geral) migrassem corretamente, mas isso também foi basicamente uma exportação e uma importação.
Desenvolvimento assistido por IA com Claude Code
Claude Code foi basicamente o que nos permitiu fazer o que queríamos fazer há anos. Todos em nossa equipe estão tão ocupados que nunca teríamos tido tempo de fazer um bom trabalho nesta migração. Também não fazia sentido contratar o trabalho.
Aproveitamos fortemente várias sessões, CLAUDE.md e vários outros arquivos .md para manter o projeto no caminho certo.
A parte em que Claude Code realmente ajudou mais foi na construção de nove ferramentas de desenvolvimento separadas que ficam diretamente no repositório. Conseguimos aproveitar scripts de construção personalizados que também mantêm essas ferramentas de desenvolvimento fora da construção de produção.
A imagem em destaque desta postagem mostra a aparência do painel do Dev Tools.
A maioria dessas ferramentas é gerenciada por scripts de auditoria individuais dedicados a produzir os resultados necessários. Assim, por exemplo, temos um script lighthouse.js, um script de estrutura de site e assim por diante.
Construímos o seguinte:
Estrutura do site
Esta foi inicialmente uma das ferramentas mais úteis, porque serviu como uma pequena ferramenta integrada do tipo Screaming Frog. Poderíamos facilmente identificar URLs que não estavam no mapa do site, metadados ausentes/duplicados, etc.
Também nos ajudou a identificar URLs que pertenciam a diferentes subpastas.
Auditor Farol
Como qualquer SEO que se preze lhe dirá, o Lighthouse é muito mais do que apenas velocidade da página e desempenho do site. Fizemos muitas melhorias e ainda temos mais pela frente.
O fato do site, em produção, ser todo estático obviamente ajuda.
Auditor de esquema
Estaremos trabalhando mais neste, mas foi uma ótima ferramenta para nos ajudar a garantir que tínhamos uma linha de base de dados de esquema em vigor.
Auditor AEO
A ferramenta do auditor AEO está longe de ser abrangente, mas ajudou-nos a cobrir muitos dos aspectos básicos.
Detalhes do esquema
A ferramenta Schema Details nos ajudou a analisar, página por página, o que precisávamos melhorar em termos de cobertura.
Visualização do gráfico aberto
A ferramenta de visualização Open Graph eu uso muito, porque ela nos permite visualizar a aparência de uma página quando compartilhada nas redes sociais.
Dentro da ferramenta, você pode clicar em cada página e aparecerá um visualizador que mostra como ficará no Facebook, LinkedIn, X e Slack.
Posso ver que já tenho uma página para consertar depois de terminar este post.
Similaridade de conteúdo – grupos de tópicos
Após a conclusão da migração, adicionei este porque queria entender o agrupamento semântico do site.
Vetorizamos todo o site usando o modelo totalmente MiniLM-L6-v2, um belo modelo de embeddings de 384 dimensões que roda completamente localmente, de @xenova/transformers.
Foi mais que suficiente para esta primeira execução.
Similaridade de conteúdo – Tabela de tópicos
Os embeddings também permitiram a criação de mais algumas subferramentas.
A primeira foi uma tabela de tópicos. Este ainda precisa de mais trabalho e ajuste de parâmetros, mas nos deu uma visão geral decente dos principais tópicos abordados.
Similaridade de conteúdo – pares semelhantes
Também geramos um relatório de similaridade de conteúdo, para que possamos voltar e combinar/mesclar conteúdo que seja muito semelhante ou gastar tempo em cada um para torná-lo mais diferenciado, se isso fizer sentido.
Similaridade de conteúdo – núcleos semânticos
O conceito de núcleo semântico é uma das coisas-chave para entender sobre qualquer site, na minha opinião, porque está relacionado a como os LLMs e os motores de busca entendem, em um nível geral, do que se trata o seu site.
Vinculação interna
A auditoria de links internos, quando você tem os embeddings de um site, é um dos melhores processos que você pode executar para ajudar os motores a entender quais tópicos e páginas estão mais relacionados.
Nunca gostei das ferramentas que estavam disponíveis para WordPress para isso, então estamos felizes por ter isso agora.
No entanto, temos muita otimização a fazer aqui.
Redirecionamentos
A ferramenta Redirecionamentos foi inestimável para garantir que não perdêssemos nada importante.
Como podemos ver facilmente em cada um deles, nosso trabalho de dar os retoques finais no site está longe de terminar, mas estamos em uma posição muito melhor para corrigir os problemas restantes e saber exatamente no que focar.
Pesquisa do lado do cliente sem dependências externas
Jekyll gera um arquivo /search.json em tempo de construção. É uma matriz JSON de cada página e postagem com título, URL, conteúdo (até 400 caracteres), tags, data e tipo indexado no arquivo. A página de pesquisa busca um único arquivo JSON e executa a correspondência de substring no navegador. Ele pontua cada elemento dos metadados (por exemplo, título 10x, tags 5x, etc.) com pesos e limita os resultados retornados em 30.
Isso nos permitiu ter indexação completa do site e capacidade de pesquisa sem Algolia, sem Elastic, sem Lunr.js, sem API de servidor.
As estatísticas atuais são de 398 entradas e isso será facilmente dimensionado para 2.500-3.000 páginas antes de precisarmos fazer qualquer otimização. Estimamos que a latência de pesquisa ainda permanecerá abaixo de 3 ms, mesmo em 5.000 páginas, portanto, estaremos bem por muito tempo.
Arquitetura SEO
Queríamos dados estruturados em todas as páginas desde o primeiro dia.
Cada página do site possui esquema JSON-LD – Organização e WebSite em todas as páginas, BreadcrumbList em tudo, exceto na página inicial, FAQPage em qualquer página com conteúdo de FAQ, BlogPosting em postagens de blog e SoftwareApplication em páginas de produtos.
O esquema de FAQ é gerado automaticamente a partir do assunto inicial. Nós adicionamos um faq_schema bloco para o YAML e o modelo cuida do resto. Nenhuma edição manual de JSON-LD é necessária. Foi assim que chegamos a mais de 470 entradas de FAQ em 128 páginas sem gastar muito tempo.
Tags canônicas, meta Open Graph e feed RSS usam site.url então eles são resolvidos corretamente por ambiente.
O robots.txt também reconhece o ambiente – o teste bloqueia todos os bots, exceto Screaming Frog e Sitebulb, a produção permite tudo.
O GTM e o Google Analytics só carregam depois que o usuário aceita o banner de consentimento de cookies. Na preparação, o banner de consentimento nem sequer é renderizado. Isso mantém nossas análises limpas e nosso ambiente de teste invisível ao rastreamento.
O mapa do site é gerenciado pelo plugin jekyll-sitemap, que apenas o gera a partir da saída do build. Sem manutenção manual.
Uma coisa que eu não esperava perder tempo eram os cabeçalhos da Política de Segurança de Conteúdo.
Cada vez que implantávamos, algo novo acontecia: primeiro, o próprio farol analítico da Cloudflare era bloqueado, depois o rastreamento de conversões do Google Ads e, por fim, a biblioteca de mapas Leaflet em nossa página SEO internacional.
Passamos por cerca de seis rodadas de atualizações do CSP antes que tudo estivesse limpo.
Transferência de produção
Executamos dois ambientes em Cloudflare Pages do mesmo repositório.
O main branch é produção e qualquer outro branch é implantado como uma visualização.
O build.sh script verifica o CF_PAGES_BRANCH variável de ambiente e conjuntos JEKYLL_ENV de acordo. As compilações de produção removem o diretório dev-tools e mantêm o mapa do site. As compilações de teste removem o mapa do site e adicionam cabeçalhos noindex.
A transição do DNS foi simples porque já gerenciamos nosso DNS na Cloudflare.
Adicionando www.demandsphere.com como um domínio personalizado no projeto Pages trocou automaticamente o CNAME de Kinsta para Pages.
Após a transição, executamos um rastreamento do Screaming Frog e encontramos alguns problemas para corrigir.
Também descobrimos que nosso favicon não aparecia nos resultados de pesquisa do Google.
Dois problemas: a raiz /favicon.ico estava retornando um 404 porque não o havíamos copiado para o diretório raiz e nosso favicon PNG tinha apenas 32×32 pixels. O Google exige pelo menos 48×48. Adicionamos um PNG 96×96, um PNG 48×48, um manifesto da web e um ICO adequado de vários tamanhos na raiz.
O cache de favicon do Google demora para ser atualizado, mas a configuração técnica agora está correta.
O que vem a seguir
Ainda há muito a fazer.
Temos cerca de 65 imagens com mais de 100 KB que precisam de otimização. A maioria de nossas 288 postagens de blog migradas possui apenas uma tag genérica “Blog” e podem usar categorização adequada.
No geral, está funcionando bem e estamos muito felizes com a migração. Agora podemos executar novas ideias de conteúdo com muito mais rapidez e qualidade muito mais alta do que jamais fomos capazes de fazer antes.
Fonte: theverge
