Migrar desde Docusaurus

Migra un sitio público de Docusaurus 2 o 3 con el scraper de Mintlify. Si necesitas un control más preciso sobre las versiones, el contenido localizado o los componentes personalizados de React, migra desde tu repositorio fuente.

Para sitios complejos, combina ambos métodos. Haz scraping de tu sitio público para crear un docs.json inicial y convertir componentes, y luego compara el resultado con el repositorio fuente para detectar contenido faltante.

mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.com

Si tu documentación de Docusaurus utiliza una ruta base, filtra para hacer scraping de esa ruta:

npx @mintlify/scraping@latest section https://example.com --filter=/docs

El scraper detecta Docusaurus, expande su barra lateral, descarga las imágenes alcanzables, convierte componentes renderizados comunes en componentes de Mintlify y crea un docs.json a partir de la navegación publicada.

Cuando el scraper termine, compara la navegación de Mintlify generada con tu sidebars.js, sidebars.ts u otra estructura de navegación de Docusaurus. Comprueba las categorías contraídas, los enlaces externos, las páginas índice de categorías generadas y las páginas excluidas de la barra lateral publicada.

Copia el siguiente contenido fuente en una rama de migración o directorio de trabajo separados.

• Tu directorio de contenido de documentación configurado, que en Docusaurus es docs/ por defecto
• sidebars.js, sidebars.ts u otros archivos de configuración de la barra lateral
• docusaurus.config.js o docusaurus.config.ts
• Archivos _category_.json, _category_.yml o _category_.yaml
• El directorio static/ y los recursos almacenados junto a las páginas de documentación
• versioned_docs/, versioned_sidebars/ y versions.json
• Documentación localizada bajo i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/, como current/
• Componentes de React importados por las páginas MDX

Copia las páginas Markdown y MDX en tu proyecto de Mintlify. Cada página necesita frontmatter con al menos un title.

---
title: "Comenzar"
description: "Instala el SDK y realiza tu primera solicitud."
---

Las barras laterales de Docusaurus son JavaScript o TypeScript ejecutable, mientras que la navegación de Mintlify son datos en docs.json. Convierte la barra lateral resuelta, no solo su texto fuente, si la barra lateral utiliza funciones o generadores personalizados.

Docusaurus utiliza la jerarquía de archivos para las barras laterales autogeneradas. Mintlify te permite organizar la navegación independientemente de las ubicaciones de los archivos, por lo que no necesitas renombrar páginas únicamente para que coincidan con la barra lateral.

El Markdown estándar suele funcionar sin cambios. Revisa la sintaxis y las importaciones específicas de Docusaurus.

Los componentes personalizados de React no se migran automáticamente desde tu repositorio fuente. Determina si cada componente es contenido, presentación o comportamiento de aplicación.

• Sustituye los patrones de contenido por un componente de Mintlify.
• Convierte el contenido repetido en un snippet reutilizable.
• Añade un componente de React cuando necesites una interacción que ningún componente integrado ofrezca.
• Traslada las páginas de aplicación completas fuera del sitio de documentación o recréalas como diseños de página personalizados.

Docusaurus combina el routeBasePath del plugin de docs, el slug del frontmatter de la página, la versión y el idioma para crear una URL. Crea un inventario a partir del sitemap publicado en lugar de inferir cada URL a partir de los nombres de archivo.

Cuando renombres o reorganices una página, añade su ruta publicada anterior a redirecciones. Prueba los enlaces con y sin la ruta base anterior, por ejemplo /docs/getting-started y /getting-started.

Revisa los IDs de encabezado explícitos de Docusaurus como:

## Configure the client {/* #configure-client */}

Conviértelos a la sintaxis de ID de encabezado personalizada de Mintlify cuando debas conservar los enlaces de ancla entrantes:

## Configure the client [#configure-client]

Docusaurus admite recursos globales en static/ y recursos almacenados junto a las páginas versionadas. Copia ambos tipos al repositorio de Mintlify.

• Un archivo de Docusaurus en static/img/logo.png normalmente se publica como /img/logo.png. Conserva esa ruta pública o actualiza todas las referencias.
• Resuelve las importaciones @site/static/... antes de eliminar las importaciones de Docusaurus.
• Mantén los recursos versionados colocados junto a la página con la versión correcta, o muévelos a directorios de recursos específicos por versión.
• Revisa las imágenes de fondo CSS y las importaciones de componentes React, que un inventario basado solo en Markdown puede pasar por alto.
• No dejes recursos requeridos en producción en tu despliegue anterior a menos que planees mantener ese hosting después de la migración.

Docusaurus almacena las versiones congeladas en versioned_docs/version-<name> y su navegación en versioned_sidebars/. Asocia cada versión mantenida a una versión de Mintlify. Decide si current, la última versión lanzada u otra versión debe ser la predeterminada.

Asocia los directorios de idiomas de Docusaurus a la navegación por idiomas de Mintlify. Conserva el prefijo de idioma en las redirecciones cuando el sitio anterior usaba rutas como /fr/docs/....

Si tu repositorio fuente contenía páginas no publicadas o restringidas, configura la autenticación y la visibilidad de las páginas, y luego prueba tu sitio como usuario no autenticado y como miembro de cada grupo.

Localiza los archivos OpenAPI o AsyncAPI referenciados por plugins, páginas personalizadas o scripts de compilación. Añade la especificación original al repositorio de Mintlify y configura las páginas generadas a partir de OpenAPI. No migres el HTML renderizado de los endpoints cuando la especificación fuente esté disponible.

Compara las páginas migradas con las entradas de tu barra lateral y con el sitemap publicado, y luego previsualiza cada versión e idioma que mantengas.

Busca en tus archivos convertidos restos de sintaxis de Docusaurus, que se renderizan como texto literal o hacen fallar la compilación: @theme, @site, :::, DocCardList, useDocusaurusContext e importaciones de plugins personalizados.

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.

• Configuración del plugin de docs
• Barras laterales
• Versionado
• Internacionalización
• Recursos estáticos
• IDs de encabezado