Migrando desde Docusaurus

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

Principales similitudes entre Docusaurus y Astro

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

Astro y Docusaurus son constructores de sitios web modernos basados en JavaScript (Jamstack), orientadas al contenido, como sitios de documentación.
Astro y Docusaurus admiten páginas MDX. Deberías poder utilizar tus archivos .mdx existentes en Astro.
Astro y Docusaurus usan el enrutamiento basado en archivos para generar rutas de de página automáticamente para cualquier archivo MDX ubicado en src/pages. El uso de la estructura de archivos de Astro para tu contenido existente y al agregar nuevas páginas debería ser familiar.
Astro tiene una integración oficial para usar componentes de React. Ten en cuenta que en Astro, los archivos de React deben tener la extensión .jsx o .tsx.
Astro admite la instalación de paquetes de NPM, incluyendo varios para React. Podrás conservar algunos o todos tus componentes y dependencias existentes de React.
La sintaxis similar a JSX de Astro debería resultarte familiar si estás acostumbrado a escribir en React.

Principales diferencias entre Docusaurus y Astro

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

Docusaurus es una aplicación de una sola página (SPA) construida en React. Los sitios de Astro son aplicaciones de varias páginas construidas utilizando componentes .astro, pero también puede admitir React, Preact, Vue.js, Svelte, SolidJS, AlpineJS, Lit y plantillas de HTML sin procesar.
Docusaurus fue diseñado para construir sitios web de documentación y tiene algunas características integradas, específicas para sitios web de documentación que tendrás que construir por ti mismo en Astro. En cambio, Astro ofrece algunas de estas características a través de un tema oficial de documentación. ¡Este sitio web fue la inspiración para esa plantilla! También puedes encontrar más temas de documentación de la comunidad con características integradas en nuestro mostrador de temas.
Los sitios de Docusaurus utilizan páginas MDX para el contenido. El tema de documentación de Astro utiliza archivos Markdown (.md) por defecto y no requiere que utilices MDX. Opcionalmente puedes instalar la integración de MDX de Astro y usar archivos .mdx además de los archivos de Markdown estándar.

Migrar de Docusaurus a Astro

Para convertir un sitio de documentación de Docusaurus a Astro, empieza con nuestra plantilla oficial de inicio para documentación Starlight, o explora más temas de la comunidad en nuestro catálogo de temas.

Puedes pasar el argumento --template al comando create astro para empezar un nuevo proyecto de Astro con una de nuestras plantillas oficiales. O, puedes comenzar un nuevo proyecto desde cualquier repositorio de Astro existente en GitHub.

npm create astro@latest -- --template starlight

pnpm create astro@latest --template starlight

yarn create astro --template starlight

Añade nuestra integración de MDX y lleva tus archivos de contenido existentes para crear páginas MDX. Todavía puedes aprovechar el enrutamiento basado en archivos copiando estos documentos directamente en src/pages/ en Astro, la misma carpeta que usas actualmente. Crea carpetas con nombres que correspondan a tu proyecto existente de Docusaurus y deberías poder mantener tus URLs existentes.

Docusaurus probablemente maneje gran parte del diseño y los metadatos de tu sitio por ti. Es posible que desees leer acerca de cómo construir diseños en Astro como envoltorios para páginas Markdown ó MDX ademas de cómo administrar la plantilla por ti mismo en Astro, incluyendo la sección <head> de tu página.

Puedes encontrar la plantilla inicial de documentación 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 solo clic para abrir un proyecto de trabajo en los entornos de desarrollo en línea de StackBlitz, CodeSandbox y Gitpod.