Elige un método
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.
Migrar un sitio público
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.
Migrar desde el código fuente
- Tu directorio de contenido de documentación configurado, que en Docusaurus es
docs/por defecto sidebars.js,sidebars.tsu otros archivos de configuración de la barra lateraldocusaurus.config.jsodocusaurus.config.ts- Archivos
_category_.json,_category_.ymlo_category_.yaml - El directorio
static/y los recursos almacenados junto a las páginas de documentación versioned_docs/,versioned_sidebars/yversions.json- Documentación localizada bajo
i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/, comocurrent/ - Componentes de React importados por las páginas MDX
Docusaurus puede cambiar su directorio de docs, su ruta base, su generador de barra lateral y los archivos incluidos en la configuración del plugin de docs. Según tu configuración, tu contenido puede estar en un directorio distinto de
docs/.title.
Ejemplo de frontmatter
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.
Convertir MDX 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.
Conservar rutas y enlaces
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:
Migrar recursos
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.pngnormalmente 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.
Migrar versiones e idiomas
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.
Migrar documentación de API
Revisa tu migració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.