Migrar Docusaurus para Astro Starlight

Por que Migrar do Docusaurus para Astro Starlight

Docusaurus serviu bem o ecossistema de documentação do React. Os times conseguiam criar sites de docs com versionamento, busca e suporte a MDX rapidamente. Mas ele entrega um runtime completo de React para cada visitante, e esse peso aparece em toda auditoria do Lighthouse.

Astro Starlight foi construído especificamente para documentação. Ele renderiza HTML estático por padrão, não envia JavaScript a menos que você opte explicitamente, e inclui busca integrada, navegação de sidebar e i18n fora da caixa. Seus arquivos MDX são transferidos diretamente. O time do Astro mantém o caminho de migração bem documentado.

Se seu site Docusaurus está lento em mobile, se os tempos de build continuam aumentando conforme seus docs crescem, ou se você está cansado de lutar com problemas de hidratação do React em conteúdo que deveria ser estático — Starlight resolve tudo isso.

Os Problemas Reais com Docusaurus em Escala

Overhead de JavaScript no Cliente

Docusaurus entrega React ao navegador. Cada carregamento de página inclui o runtime do React, React DOM e a camada de roteamento do lado do cliente. Para um site de documentação onde 99% das páginas são texto estático e blocos de código, isso é peso morto. Scores de Lighthouse em mobile normalmente ficam entre 45-65 por causa disso.

Degradação de Performance de Build

Conforme sua coleção de docs cresce passando de algumas centenas de páginas, os builds do Docusaurus desaceleram notavelmente. O bundling do Webpack piora. Times com 500+ páginas de docs relatam tempos de build excedendo 5 minutos, o que mata loops de feedback de CI/CD.

Lock-In do Ecossistema de Plugins

Plugins do Docusaurus são fortemente acoplados à sua arquitetura interna. Precisa de plugins remark customizados? Funcionam, mas a camada de configuração adiciona complexidade. Quer trocar o provedor de busca? Você está trabalhando dentro do sistema de presets do Docusaurus, que limita o que é possível.

Rigidez de Configuração de Sidebar

Configs de sidebar do Docusaurus usam um esquema JSON/JS específico com campos category, items e type. Funciona, mas a configuração fica difícil de manejar para grandes árvores de docs com aninhamento profundo. Reordenar seções significa editar arquivos de config em vez de apenas mover arquivos.

Dependências de Componentes React

Componentes customizados no Docusaurus são componentes React que hidratam no cliente. Se você construiu exemplos interativos, conteúdo em abas ou admonições customizadas, todos carregam o custo de hidratação do React — mesmo quando a interatividade é mínima.

O que Astro Starlight Oferece

Zero-JS por Padrão

Starlight gera HTML e CSS puro estático. Nenhum runtime de framework é enviado ao navegador a menos que você explicitamente adicione uma ilha interativa. Páginas de documentação carregam em menos de 200ms em conexões 3G. Scores de Lighthouse atingem 95-100 consistentemente.

Compatibilidade com MDX

Starlight inclui a integração MDX do Astro por padrão. Seus arquivos .mdx existentes funcionam imediatamente. Campos de frontmatter mapeiam limpadiamente — title, description, sidebar_label todos têm equivalentes em Starlight. Plugins remark e rehype se transferem sem mudanças.

Busca Pagefind Integrada

Starlight vem com Pagefind, um mecanismo de busca estático que indexa seu HTML construído e funciona inteiramente no navegador. Sem serviço externo, sem chaves de API, sem atrasos de crawl do Algolia. A busca funciona offline e adiciona aproximadamente 10KB ao seu bundle. Para times que especificamente precisam do Algolia, há um plugin oficial do Starlight para DocSearch.

Geração de Sidebar Baseada em Arquivo

Starlight pode gerar sidebars automaticamente a partir da sua estrutura de arquivos. Coloque um arquivo MDX em uma pasta, ele aparece no sidebar. Você ainda pode substituir com configuração explícita, mas o comportamento padrão elimina a maioria da manutenção de config de sidebar.

Content Collections com Type Safety

Starlight usa content collections do Astro, que validam seu frontmatter contra um esquema Zod em tempo de build. Erros de digitação em campos de frontmatter são capturados antes da implantação, não descobertos por usuários.

Nosso Processo de Migração

Fase 1: Auditoria e Planejamento

Começamos inventariando seu site Docusaurus — contagem de páginas, componentes customizados, uso de plugins, estrutura de sidebar, setup de versionamento e qualquer tema customizado. Mapeamos cada feature do Docusaurus para seu equivalente em Starlight e sinalizamos lacunas que precisam de soluções customizadas.

Fase 2: Scaffolding do Starlight

Criamos um novo projeto Starlight usando yarn create astro --template starlight e configuramos para combinar com a estrutura do seu site existente. Configuramos content collections, definimos o astro.config.mjs e estabelecemos a hierarquia de pasta que espelha sua estrutura de URL atual.

Fase 3: Migração de Conteúdo

Arquivos MDX são transferidos com mudanças mínimas. Processamos:

• Remapeamento de frontmatter: Campos específicos do Docusaurus como sidebar_position, sidebar_label e slug são convertidos para o esquema de frontmatter do Starlight
• Atualizações de import statements: Imports de componentes mudam de caminhos do Docusaurus para caminhos de componentes Astro
• Sintaxe de admonição: Docusaurus usa sintaxe :::note; Starlight usa componentes <Aside> ou sua própria sintaxe de admonição
• Componentes de abas: <Tabs> e <TabItem> do Docusaurus são substituídos pelos componentes de aba integrados do Starlight

Fase 4: Remapeamento de Config de Sidebar

Configs de sidebar do Docusaurus usando padrões category/items são convertidos para o formato de configuração de sidebar do Starlight. Quando possível, mudamos para sidebars auto-gerados impulsionados pela estrutura de arquivo, reduzindo a manutenção de config a zero.

// Docusaurus sidebars.js
module.exports = {
  docs: [
    { type: 'category', label: 'Getting Started', items: ['intro', 'installation'] },
  ],
};

// Starlight astro.config.mjs
starlight({
  sidebar: [
    { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
  ],
})

Fase 5: Mapeamento de Plugins e Integrações

Replazamos plugins do Docusaurus com integrações Astro:

• @docusaurus/plugin-google-gtag → @astrojs/partytown do Astro com gtag inline
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind (integrado) ou plugin starlight-docsearch
• @docusaurus/plugin-client-redirects → Redirects do Astro em config ou astro-redirect
• Plugins remark/rehype customizados → Transferência direta, mesmo ecossistema de plugin

Fase 6: Migração de Busca

Se você está no Algolia DocSearch, migramos para Pagefind por padrão. Pagefind indexa em tempo de build, não requer serviço externo e entrega busca instantânea com fuzzy matching. Se seu time especificamente precisa do Algolia — para analytics ou respostas com IA — configuramos o plugin oficial starlight-algolia em seu lugar.

Fase 7: QA e Lançamento

Fazemos um crawl completo de comparação entre sites antigo e novo, verificamos que toda URL é resolvida, testamos funcionalidade de busca, validamos renderização mobile e confirmamos que scores de Lighthouse atingem nossos alvos.

Estratégia de Preservação de SEO

Sites de documentação acumulam autoridade de busca significativa. Protegemos cada bit dela:

• Paridade de URL: Combinamos sua estrutura de URL existente exatamente. Se Docusaurus serviu /docs/getting-started, Starlight serve o mesmo caminho
• Redirects 301: Para qualquer URL que deve mudar, configuramos redirects no nível de servidor em Vercel ou Cloudflare
• Tags canônicas: Cada página recebe uma URL canônica apropriada
• Geração de sitemap: @astrojs/sitemap produz um sitemap atualizado submetido ao Search Console
• Preservação de meta: Title tags, meta descriptions e tags Open Graph são transferidas do frontmatter existente
• Dados estruturados: Adicionamos JSON-LD específico de documentação quando aplicável

Timeline e Preços

A maioria das migrações do Docusaurus para Starlight são completadas em 1-3 semanas dependendo da complexidade do site:

• Sites pequenos (menos de 50 páginas, componentes customizados mínimos): 1 semana, começando em R$ 15.000
• Sites médios (50-200 páginas, componentes customizados, versionamento): 2 semanas, começando em R$ 30.000
• Sites grandes (200+ páginas, customização pesada, múltiplos locales): 3+ semanas, começando em R$ 50.000

Todo projeto começa com uma auditoria de migração gratuita onde avaliamos seu setup específico do Docusaurus e fornecemos um escopo exato e timeline.