Saltearse al contenido
Astro Astro

Migrando desde GitBook

Gitbook es una plataforma basada en la web para crear, publicar documentación y libros de manera colaborativa, con integración de control de versiones y funciones personalizables.

Principales similitudes entre GitBook y Astro

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

  • Astro y GitBook admiten Markdown. Puedes migrar toda tu documentación existente utilizando la función Git Sync de GitBook.

  • Tanto Astro como Gitbook usan algún tipo de enrutamiento basado en archivos. El uso de la estructura de archivos de Astro para tu contenido existente y al agregar nuevas páginas debería resultarte familiar.

Principales diferencias entre GitBook y Astro

Cuando migres tu documentación de GitBook a Astro, notarás algunas diferencias importantes:

  • Un sitio de GitBook se edita usando un panel en línea. En Astro, usarás un editor de código y un 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, CodeSandbox o Gitpod.

  • GitBook guarda 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 admite Markdoc a través de la integración opcional de Markdoc, que presenta una sintaxis similar a la que usarías en GitBook.

Migrar de GitBook a Astro

Para migrar un sitio de documentación de GitBook a Astro, comienza con nuestra plantilla oficial de inicio para documentación Starlight o explora más temas de documentación 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.

Terminal window
npm create astro@latest -- --template starlight

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

Para sincronizar directamente con la colección de contenido de la plantilla de documentación, 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 la sincronización de git 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 ser creados y agregados a tu proyecto a traves del atributo tags de la configuración de Markdoc o eliminados de tus archivos.

Recursos de la comunidad

  • ¡Añade el tuyo!

Más guías de migración