Migrar Docusaurus a Astro Starlight

Por Qué Migrar de Docusaurus a Astro Starlight

Docusaurus ha servido bien al ecosistema de documentación de React. Los equipos podían crear sitios de documentación con versionado, búsqueda y soporte MDX bastante rápido. Pero envía un runtime de React completo a cada visitante, y ese peso se nota en cada auditoría de Lighthouse.

Astro Starlight está construido específicamente para documentación. Renderiza HTML estático por defecto, no envía JavaScript a menos que explícitamente lo solicites, e incluye búsqueda integrada, navegación lateral e i18n lista para usar. Tus archivos MDX se transfieren directamente. El equipo de Astro mantiene bien documentada la ruta de migración.

Si tu sitio Docusaurus se siente lento en móvil, si los tiempos de compilación siguen aumentando a medida que tu documentación crece, o si estás cansado de luchar con problemas de hidratación de React en lo que debería ser contenido estático — Starlight soluciona todo eso.

Los Problemas Reales de Docusaurus a Escala

Sobrecarga de JavaScript del Lado del Cliente

Docusaurus envía React al navegador. Cada carga de página incluye el runtime de React, React DOM y la capa de enrutamiento del lado del cliente. Para un sitio de documentación donde el 99% de las páginas es texto estático y bloques de código, esto es peso muerto. Las puntuaciones móviles de Lighthouse típicamente caen entre 45-65 por esto.

Degradación del Rendimiento de Compilación

A medida que tu colección de documentación crece más allá de algunos cientos de páginas, las compilaciones de Docusaurus se ralentizan notablemente. El bundling de Webpack lo empeora. Los equipos con 500+ páginas de documentación reportan tiempos de compilación superiores a 5 minutos, lo que mata los bucles de retroalimentación de CI/CD.

Bloqueo del Ecosistema de Plugins

Los plugins de Docusaurus están fuertemente acoplados a su arquitectura interna. ¿Necesitas plugins remark personalizados? Funcionan, pero la capa de configuración agrega complejidad. ¿Quieres cambiar el proveedor de búsqueda? Estás trabajando dentro del sistema de presets de Docusaurus, que limita lo que es posible.

Rigidez de Configuración de Barra Lateral

Las configuraciones de barra lateral de Docusaurus usan un esquema JSON/JS específico con campos category, items y type. Funciona, pero la configuración se vuelve engorrosa para árboles de documentación grandes con anidamiento profundo. Reordenar secciones significa editar archivos de configuración en lugar de simplemente mover archivos.

Dependencias de Componentes React

Los componentes personalizados en Docusaurus son componentes React que se hidratan en el cliente. Si has creado ejemplos interactivos, contenido con pestañas o admoniciones personalizadas, todos tienen el costo de hidratación de React — incluso cuando la interactividad es mínima.

Lo Que Astro Starlight Te Ofrece

Cero JS por Defecto

Starlight genera HTML y CSS puro estático. Ningún runtime de framework se envía al navegador a menos que explícitamente agregues una isla interactiva. Las páginas de documentación se cargan en menos de 200ms en conexiones 3G. Las puntuaciones de Lighthouse alcanzan consistentemente 95-100.

Compatibilidad MDX

Starlight incluye la integración MDX de Astro por defecto. Tus archivos .mdx existentes funcionan inmediatamente. Los campos de frontmatter se mapean limpiamente — title, description, sidebar_label tienen todos equivalentes de Starlight. Los plugins remark y rehype se transfieren sin cambios.

Búsqueda Pagefind Integrada

Starlight viene con Pagefind, un motor de búsqueda estático que indexa tu HTML compilado y se ejecuta completamente en el navegador. Sin servicio externo, sin claves API, sin retrasos de rastreo de Algolia. La búsqueda funciona sin conexión y agrega aproximadamente 10KB a tu bundle. Para equipos que específicamente necesitan Algolia, hay un plugin oficial de Starlight para DocSearch.

Generación de Barra Lateral Basada en Archivos

Starlight puede generar automáticamente barras laterales desde tu estructura de archivos. Coloca un archivo MDX en una carpeta y aparece en la barra lateral. Aún puedes anular con configuración explícita, pero el comportamiento predeterminado elimina la mayoría del mantenimiento de configuración de barra lateral.

Colecciones de Contenido con Seguridad de Tipo

Starlight usa colecciones de contenido de Astro, que validan tu frontmatter contra un esquema Zod en tiempo de compilación. Los errores tipográficos en campos de frontmatter se detectan antes del despliegue, no los descubren los usuarios.

Nuestro Proceso de Migración

Fase 1: Auditoría y Planificación

Comenzamos inventariando tu sitio Docusaurus — conteo de páginas, componentes personalizados, uso de plugins, estructura de barra lateral, configuración de versionado y cualquier tema personalizado. Mapeamos cada característica de Docusaurus a su equivalente de Starlight e identificamos las brechas que necesitan soluciones personalizadas.

Fase 2: Scaffolding de Starlight

Generamos un nuevo proyecto de Starlight usando yarn create astro --template starlight y lo configuramos para que coincida con la estructura de tu sitio existente. Configuramos colecciones de contenido, establecemos astro.config.mjs y creamos la jerarquía de carpetas que refleja tu estructura de URL actual.

Fase 3: Migración de Contenido

Los archivos MDX se transfieren con cambios mínimos. Manejamos:

• Remapeo de frontmatter: Los campos específicos de Docusaurus como sidebar_position, sidebar_label y slug se convierten al esquema de frontmatter de Starlight
• Actualizaciones de declaraciones de importación: Las importaciones de componentes cambian de rutas de Docusaurus a rutas de componentes de Astro
• Sintaxis de admoniciones: Docusaurus usa sintaxis :::note; Starlight usa componentes <Aside> o su propia sintaxis de admoniciones
• Componentes de pestañas: <Tabs> y <TabItem> de Docusaurus se reemplazan con componentes de pestañas integrados de Starlight

Fase 4: Remapeo de Configuración de Barra Lateral

Las configuraciones de barra lateral de Docusaurus usando patrones category/items se convierten al formato de configuración de barra lateral de Starlight. Cuando es posible, cambiamos a barras laterales generadas automáticamente impulsadas por la estructura de archivos, reduciendo el mantenimiento de configuración a cero.

// 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: Mapeo de Plugin e Integración

Reemplazamos plugins de Docusaurus con integraciones de Astro:

• @docusaurus/plugin-google-gtag → @astrojs/partytown de Astro con gtag inline
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind (integrado) o plugin starlight-docsearch
• @docusaurus/plugin-client-redirects → Redirecciones de Astro en config o astro-redirect
• Plugins remark/rehype personalizados → Transferencia directa, mismo ecosistema de plugins

Fase 6: Migración de Búsqueda

Si estás en Algolia DocSearch, migramos a Pagefind por defecto. Pagefind indexa en tiempo de compilación, no requiere servicio externo y entrega búsqueda instantánea con coincidencia difusa. Si tu equipo específicamente necesita Algolia — para análisis o respuestas potenciadas por IA — configuramos el plugin oficial starlight-algolia en su lugar.

Fase 7: QA y Lanzamiento

Ejecutamos un rastreo completo comparativo entre sitios antiguos y nuevos, verificamos que cada URL se resuelve, probamos la funcionalidad de búsqueda, validamos la representación móvil y confirmamos que las puntuaciones de Lighthouse cumplan nuestros objetivos.

Estrategia de Preservación SEO

Los sitios de documentación acumulan autoridad de búsqueda significativa. Protegemos cada bit:

• Paridad de URL: Coincidimos con tu estructura de URL existente exactamente. Si Docusaurus servía /docs/getting-started, Starlight sirve la misma ruta
• Redirecciones 301: Para cualquier URL que deba cambiar, configuramos redirecciones a nivel de servidor en Vercel o Cloudflare
• Etiquetas canónicas: Cada página obtiene una URL canónica adecuada
• Generación de sitemap: @astrojs/sitemap produce un sitemap actualizado enviado a Search Console
• Preservación de metadatos: Las etiquetas de título, descripciones meta y etiquetas Open Graph se transfieren desde frontmatter existente
• Datos estructurados: Agregamos datos JSON-LD específicos de documentación donde corresponda

Cronograma y Precios

La mayoría de migraciones de Docusaurus a Starlight se completan en 1-3 semanas dependiendo de la complejidad del sitio:

• Sitios pequeños (menos de 50 páginas, componentes personalizados mínimos): 1 semana, comenzando en $3,000
• Sitios medianos (50-200 páginas, componentes personalizados, versionado): 2 semanas, comenzando en $6,000
• Sitios grandes (200+ páginas, personalización pesada, múltiples locales): 3+ semanas, comenzando en $10,000

Cada proyecto comienza con una auditoría de migración gratuita donde evaluamos tu configuración específica de Docusaurus y proporcionamos un alcance exacto y cronograma.