Skip to main content
Exporta el contenido de GitBook a un repositorio Git con Git Sync para la migración más completa, o haz scraping de un sitio público de GitBook para crear un proyecto inicial de Mintlify.

​
Elige un método

Usa Git Sync como la migración principal cuando sea posible. Un sitio de GitBook está compuesto por secciones, y una sección puede tener varias variantes, mientras que Git Sync opera a nivel de sección. Exporta cada sección que aparezca en el sitio publicado.
GitBook ahora llama secciones a los contenedores de contenido dentro de un sitio. La documentación antigua de GitBook y los scripts de la comunidad los llaman espacios (spaces).

​
Exportar una sección con Git Sync

GitBook no ofrece descargas directas de Markdown para páginas individuales. Para exportar una sección como Markdown:
  1. Crea un repositorio vacío en GitHub o GitLab o una rama vacía en un repositorio de migración.
  2. En la sección que quieras exportar, haz clic en Set up junto a Git Sync en la cabecera de la sección.
  3. En la lista de proveedores, haz clic en GitHub Sync o GitLab Sync, luego autentícate si aún no has conectado el proveedor.
  4. Selecciona el repositorio vacío y la rama para la exportación.
  5. Como dirección inicial de sincronización, elige GitBook → GitHub o GitBook → GitLab.
  6. Inicia la sincronización inicial. Cuando termine, clona o descarga el repositorio.
  7. Repite el proceso con cada sección, idioma o versión que necesites migrar.
La dirección inicial de sincronización es importante. Elegir GitHub → GitBook o GitLab → GitBook reemplaza el contenido de tu sección con el de la rama seleccionada en lugar de exportar la sección. Confirma que la dirección comienza en GitBook y apunta a tu repositorio vacío. Si eliges la dirección incorrecta, revierte a la revisión anterior a la operación de Git Sync en el historial de versiones de la sección.
Mantén el repositorio sincronizado sin cambios como una instantánea de migración. Crea una rama o copia para tu conversión a Mintlify.

​
Migrar un sitio público

El scraper sobrescribe archivos existentes en un directorio.Ejecuta el scraper en un directorio vacío.
El scraper carga la navegación renderizada de GitBook, descarga las imágenes alcanzables, convierte bloques comunes y crea un docs.json. No puede recuperar secciones privadas, cambios no publicados, permisos, comentarios ni historial de revisiones. Compara el proyecto generado con tu exportación de Git Sync cuando ambos estén disponibles. El scrape es útil para comprobar la conversión de bloques renderizados. La exportación es el mejor inventario del contenido fuente.

​
Comprende la exportación de Git Sync

Normalmente, GitBook crea o usa los siguientes archivos y directorios:
  • README.md: página de inicio de la sección
  • SUMMARY.md: tabla de contenidos
  • .gitbook.yaml: raíz del contenido, estructura y redirecciones de la sección
  • .gitbook/assets/: imágenes y archivos subidos
  • .gitbook/includes/: contenido reutilizable
Las rutas pueden variar cuando la configuración de GitBook define otra raíz de contenido, página de inicio o archivo de resumen. Confirma tu configuración específica antes de mover archivos.

​
Convertir la navegación de SUMMARY.md

SUMMARY.md es una lista Markdown anidada. Convierte sus encabezados y enlaces en navegación de docs.json: Elimina las extensiones .md de las rutas de navegación, pero no renombres cada archivo antes de comprobar los enlaces. Una página como guides/README.md puede convertirse en guides/index.mdx o mantenerse como un archivo Markdown con una ruta de navegación distinta. Cada página de Mintlify también necesita frontmatter con al menos un title. Añade o convierte el frontmatter a medida que migres cada página.
Los scripts de la comunidad pueden automatizar la asignación recursiva de SUMMARY.md. Revisa los movimientos de archivos y los comandos de shell que generan antes de ejecutarlos. Un conversor debe manejar los enlaces faltantes, las URL externas, las páginas duplicadas, los grupos anidados y las raíces de contenido de GitBook sin sobrescribir los archivos fuente.

​
Convertir bloques de GitBook

GitBook representa muchos bloques con directivas {% ... %}. Convierte estas directivas en componentes de Mintlify. GitBook exporta algunos bloques personalizados como HTML porque no tienen una representación en Markdown. Revisa cada bloque HTML para verificar que funciona igual en MDX.

​
Convertir contenido reutilizable

GitBook exporta el contenido reutilizable a .gitbook/includes/ y lo referencia con directivas de inclusión. Convierte cada archivo reutilizable en un snippet de Mintlify y luego sustituye el include de GitBook por una importación MDX y un componente. Por ejemplo:
Comprueba el contenido reutilizable compartido entre varias secciones. GitBook asigna una sección padre que posee el contenido y es el único lugar donde se puede editar, por lo que las exportaciones de secciones separadas pueden contener duplicados o referencias entre secciones que deben convertirse en un único snippet compartido.

​
Migrar secciones, variantes y traducciones

Un sitio de GitBook publica una o varias secciones, organiza secciones relacionadas en grupos y utiliza variantes para versiones o idiomas. Elige el modelo de navegación de Mintlify más cercano:
  • Asocia las secciones de producto o audiencia a productos, pestañas o anclas.
  • Asocia las variantes de lanzamiento a versiones.
  • Asocia las secciones traducidas a idiomas.
  • Asocia las colecciones de contenido independientes a grupos separados cuando los usuarios no necesitan un selector.
Anota la variante predeterminada y cada slug de variante antes de cambiar el dominio. GitBook puede omitir el slug de la variante predeterminada en su URL pública, por lo que las redirecciones deben tener en cuenta tanto la ruta predeterminada como las nombradas explícitamente. Copia .gitbook/assets/ a tu repositorio de Mintlify y actualiza las rutas relativas de imágenes y descargas. Revisa las imágenes en línea que usan HTML para el tamaño o la alineación. No dejes recursos requeridos en producción en GitBook a menos que planees mantener ese hosting después de tu migración. Las redirecciones de GitBook pueden existir en tu archivo de configuración y en los ajustes a nivel de sitio. Recopila ambas fuentes y conviértelas en redirecciones de Mintlify. GitBook limita las redirecciones de su archivo de configuración a una sección, mientras que una redirección de Mintlify se aplica al sitio publicado, por lo que debes incluir el prefijo de la sección o variante anterior cuando sea necesario.

​
Migrar documentación de OpenAPI

GitBook puede almacenar especificaciones OpenAPI a nivel de organización y colocar bloques OpenAPI generados en las secciones. La exportación Markdown de la sección puede no ser la fuente de verdad de estas especificaciones.
  1. Inventaría cada especificación OpenAPI en tu organización de GitBook.
  2. Recupera el archivo original, la URL fuente alojada o la especificación mediante la API de GitBook.
  3. Añade el archivo JSON o YAML a tu repositorio de Mintlify.
  4. Configura las páginas generadas a partir de OpenAPI.
  5. Recrea las explicaciones adyacentes a partir de los bloques normales de GitBook.
  6. Compara la autenticación, las URL de servidor, los ejemplos y las extensiones OpenAPI específicas de GitBook con tus páginas de API en Mintlify.

​
Revisa tu migración

Compara cada sección exportada y cada entrada de SUMMARY.md con docs.json, luego verifica cada sección, grupo, variante e idioma. Busca en tus archivos convertidos restos de sintaxis de GitBook: {%, {% end, .gitbook/includes y los bloques HTML sin procesar que GitBook exporta en lugar de Markdown.

​
Lanza tu nuevo sitio

  • Establece una congelación de contenido en tu sitio anterior y registra cada cambio que se le realice después de la instantánea de migración.
  • Confirma tu rama y repositorio de producción en la página de ajustes de Git de tu panel.
  • Anota tus registros DNS actuales y mantén tu sitio anterior en funcionamiento hasta que verifiques que tu despliegue de Mintlify está en producción.
  • Revisa la barra de navegación, el pie de página, el favicon, el logotipo, los colores y la tipografía.
  • Revisa los metadatos del sitio y de las páginas, las URL canónicas y las preferencias de indexación. Consulta SEO y ajustes de búsqueda.
  • Instala las integraciones de analítica necesarias y, opcionalmente, añade una página 404 personalizada.
  • Si migraste una referencia de API, compara las páginas de endpoints, la estructura de navegación, las URL de servidor, los esquemas de autenticación y los ejemplos con tu sitio anterior.
  • Previsualiza tu commit exacto de lanzamiento en un despliegue de previsualización. Comprueba los diseños en escritorio y móvil, páginas de cada sección de navegación, la búsqueda y tus redirecciones.
  • Revisa la consola del navegador y la pestaña de red por si hay errores en páginas que utilicen componentes o scripts personalizados.
  • Cambia tu dominio siguiendo la guía de dominio personalizado, que cubre la migración sin tiempo de inactividad para un dominio que ya sirve documentación.
  • Tras el lanzamiento, monitorea los errores 404, los fallos de redirección y los fallos de compilación.

​
Referencias de GitBook

Temas relacionados

Descripción general de la migraciónMigrar desde FernMigrar desde Document360