Migrar desde Docusaurus

Docusaurus es un constructor popular de sitios web de documentación construido sobre React.

Similitudes clave entre Docusaurus y Astro

Docusaurus y Astro comparten algunas similitudes que te ayudarán a migrar tu proyecto:

Tanto Astro como Docusaurus son constructores de sitios modernos basados en JavaScript (Jamstack) diseñados para sitios web orientados a contenido, como sitios de documentación.
Tanto Astro como Docusaurus soportan páginas MDX. Deberías poder usar tus archivos .mdx existentes con Astro.
Tanto Astro como Docusaurus usan enrutamiento basado en archivos para generar rutas de página automáticamente para cualquier archivo MDX ubicado en src/pages. Usar la estructura de archivos de Astro para tu contenido existente y al añadir nuevas páginas debería resultarte familiar.
Astro tiene una integración oficial para usar componentes de React. Ten en cuenta que en Astro, los archivos de React deben tener una extensión .jsx o .tsx.
Astro soporta instalar paquetes NPM, incluyendo varios para React. Puede que puedas conservar algunos o todos tus componentes y dependencias de React existentes.
La sintaxis similar a JSX de Astro debería resultarte familiar si estás acostumbrado a escribir React.

Diferencias clave entre Docusaurus y Astro

Cuando reconstruyas tu sitio de Docusaurus en Astro, notarás algunas diferencias importantes:

Docusaurus es una single-page application (SPA) basada en React. Los sitios de Astro son apps multi-página construidas usando componentes .astro, pero también pueden soportar React, Preact, Vue.js, Svelte, SolidJS, AlpineJS y plantillas HTML crudo.
Docusaurus fue diseñado para construir sitios web de documentación y tiene algunas características de sitio web específicas para documentación integradas que tendrías que construir tú mismo en Astro. En su lugar, Astro ofrece algunas de estas características a través de Starlight: un tema oficial de docs. ¡Este sitio web fue la inspiración para Starlight, y ahora funciona con él! También puedes encontrar más temas de docs de la comunidad con características integradas en nuestro Themes Showcase.
Los sitios de Docusaurus usan páginas MDX para el contenido. El tema de docs de Astro usa archivos Markdown (.md) por defecto y no requiere que uses MDX. Puedes opcionalmente instalar la integración MDX de Astro (incluida en nuestro tema Starlight por defecto) y usar archivos .mdx además de los archivos Markdown estándar.

Cambiar de Docusaurus a Astro

Para convertir un sitio de documentación de Docusaurus a Astro, comienza con nuestra plantilla de inicio del tema de docs Starlight, o explora más temas de docs de la comunidad en nuestro showcase de temas.

Puedes pasar un argumento --template al comando create astro para iniciar un nuevo proyecto de Astro con uno de nuestros starters oficiales. O, puedes iniciar un nuevo proyecto desde cualquier repositorio existente de Astro en GitHub.

npm create astro@latest -- --template starlight

pnpm create astro@latest --template starlight

yarn create astro --template starlight

La integración MDX de Astro está incluida por defecto, así que puedes traer tus archivos de contenido existentes a Starlight de inmediato.

Puedes encontrar el starter de docs de Astro, y otras plantillas oficiales, en astro.new. Encontrarás un enlace al repositorio de GitHub de cada proyecto, así como enlaces de un clic para abrir un proyecto funcional en los entornos de desarrollo en línea StackBlitz y CodeSandbox.