Saltar al contenido

Migrar desde GitBook

GitBook es una plataforma basada en web para crear y publicar documentación y libros de manera colaborativa, con integración de control de versiones y características personalizables.

Similitudes clave entre GitBook y Astro

Sección titulada “Similitudes clave entre GitBook y Astro”

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

  • Tanto Astro como GitBook soportan Markdown. Puedes migrar toda tu documentación existente utilizando la función Git Sync de GitBook.

  • Tanto Astro como GitBook usan alguna forma de enrutamiento basado en archivos. Usar la estructura de archivos de Astro para tu contenido existente y al añadir nuevas páginas debería resultarte familiar.

Diferencias clave entre GitBook y Astro

Sección titulada “Diferencias clave entre GitBook y Astro”

Cuando migres tu docs de GitBook a Astro, notarás algunas diferencias importantes:

  • Un sitio de GitBook se edita usando un dashboard en línea. En Astro, usarás un editor de código y entorno de desarrollo para mantener tu sitio. Puedes desarrollar localmente en tu máquina, o elegir un editor/entorno de desarrollo en la nube como StackBlitz o CodeSandbox.

  • GitBook almacena tu contenido en una base de datos. En Astro, tendrás archivos individuales (típicamente Markdown o MDX) en tu directorio de proyecto para el contenido de cada página. O, puedes elegir usar un CMS para tu contenido y usar Astro para obtener y presentar los datos.

  • GitBook usa una sintaxis personalizada sobre Markdown para el contenido. Astro soporta Markdoc vía la integración opcional de Markdoc, que presenta una sintaxis similar a la que usarías en GitBook.

Cambiar de GitBook a Astro

Sección titulada “Cambiar de GitBook a Astro”

Para convertir un sitio de documentación de GitBook 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.

Ventana de la terminal
npm create astro@latest -- --template starlight

Una vez que tengas un nuevo proyecto de Astro, puedes sincronizar tu contenido existente de GitBook a tu nuevo proyecto de Astro. GitBook tiene una función Git Sync que sincronizará automáticamente tu contenido de GitBook a un repositorio de GitHub/GitLab.

Para sincronizar directamente a la content collection del template de docs, especifica src/content/docs/en o src/content/docs como el directorio del proyecto.

Después de sincronizar el contenido, ahora tendrás una copia de tu contenido de GitBook en tu repositorio de Astro. Deshabilita git sync para evitar futuras sincronizaciones con GitBook.

Ten en cuenta que aunque ahora tienes tu contenido migrado a tu proyecto de Astro, no será inmediatamente utilizable. Para usar este contenido en tu sitio de Astro, necesitarás pasar algo de tiempo cambiando manualmente la sintaxis de GitBook a un formato compatible con Astro. En particular:

  • La integración de Markdoc de Astro requiere que la extensión del archivo sea .mdoc. Esto es para evitar conflictos con otras extensiones de Markdown como .mdx y .md.
  • La sintaxis de GitBook difiere de Markdoc donde el prefijo / que denota una etiqueta de cierre se reemplaza con end para los archivos de GitBook. Necesitarás actualizar esta notación en todos tus archivos.
  • Algunas características de GitBook dependen de componentes personalizados. Estos componentes no existirán en Astro y deben crearse y añadirse a tu proyecto a través del atributo tags de la config de Markdoc o eliminarse de tus archivos.

Recursos de la comunidad

Sección titulada "Recursos de la comunidad"

Más guías de migración

Contribuir Comunidad Patrocinar