Migrar desde otra plataforma

Utiliza una migración manual cuando tu plataforma actual no esté en la lista de plataformas soportadas, tu sitio sea privado o necesites control total sobre la estructura resultante.

Exporta o copia todo el contenido antes de convertirlo.

1. Archivos Markdown o MDX de tu repositorio fuente
2. Una exportación nativa en Markdown o HTML desde tu plataforma actual
3. Contenido obtenido a través de la API de tu plataforma actual
4. HTML renderizado desde tu sitio publicado
5. Copia y conversión manuales

Mantén tu exportación original sin cambios. Realiza el trabajo de conversión en una copia para poder comparar o reiniciar tu migración.

Crea un inventario que contenga, para cada página, su identificador fuente, título, URL publicada, ruta de destino, tipo de contenido, versión, idioma y estado de migración. Incluye las páginas no publicadas que deban seguir estando disponibles.

Un proyecto típico de Mintlify incluye:

• Un archivo docs.json para la configuración del sitio y la navegación
• Archivos Markdown o MDX para las páginas que no se generan a partir de una especificación de API
• Imágenes y archivos descargables que quieras alojar desde tu repositorio
• Opcionalmente, especificaciones OpenAPI o AsyncAPI o esquemas GraphQL para la documentación de API generada

Consulta Páginas para conocer el frontmatter compatible y el comportamiento de los archivos.

Puedes reproducir fielmente tu estructura de navegación actual o usar la migración como una oportunidad para mejorar cómo los usuarios encuentran el contenido.

Utiliza una estructura de navegación adecuada. La siguiente tabla muestra patrones de navegación habituales para sitios alojados en Mintlify.

Añade cada ruta de página a docs.json a menos que quieras ocultar la página. Una página oculta sigue siendo accesible por URL, pero se excluye por defecto de la búsqueda del sitio, los sitemaps, la indexación en buscadores y el contexto de IA.

El Markdown simple suele necesitar poca conversión. Sustituye la sintaxis específica de la plataforma por componentes de Mintlify.

Busca en tus archivos convertidos directivas de la plataforma fuente, importaciones, variables de plantilla, HTML sin procesar e includes sin resolver. Estos patrones a menudo se renderizan como texto o hacen fallar la compilación de MDX.

Localiza la especificación OpenAPI o AsyncAPI original o el esquema GraphQL cuando exista alguno. Añade el archivo fuente a tu repositorio de Mintlify y sigue la guía de configuración correspondiente.

• Configuración de OpenAPI
• Configuración de AsyncAPI
• Configuración de GraphQL

Si tu plataforma fuente almacenaba las descripciones de endpoints fuera de la especificación, fusiona el contenido útil en la especificación o colócalo en guías adyacentes. Compara el orden de operaciones, la autenticación, las URL de servidor, los ejemplos, los esquemas y los code samples con tu sitio anterior.

Puedes generar páginas iniciales de endpoints OpenAPI con el paquete scraper de Mintlify:

npx @mintlify/scraping@latest openapi-file ./openapi.yaml -o api-reference

Copia las imágenes, vídeos, fuentes y archivos descargables que te pertenezcan a tu repositorio. Conserva las rutas públicas existentes cuando sea práctico para reducir los cambios de enlaces.

Revisa los siguientes patrones para identificar los recursos que necesitan migrarse.

• Destinos de imágenes y enlaces en Markdown
• Elementos HTML <img> y <video>
• Imágenes de fondo CSS
• Recursos referenciados por componentes importados
• Archivos alojados por tu antiguo proveedor de documentación
• Recursos específicos por versión e idioma

No dejes recursos requeridos en producción en el dominio de tu antiguo proveedor a menos que planees mantener ese hosting después de la migración.

Crea una asignación desde cada URL publicada anterior a su destino. Añade una redirección siempre que cambie la ruta.

Incluye los siguientes patrones en tu mapa de redirecciones.

• Páginas eliminadas o consolidadas durante la migración
• Prefijos de versión e idioma
• Prefijos de categoría o espacio
• Páginas de aterrizaje personalizadas
• Páginas de endpoint de API
• Slugs explícitos y aliases heredados

Las exportaciones de contenido no suelen incluir la configuración de la plataforma. Inventaría y recrea las funcionalidades que aún necesites.

• Dominio personalizado y DNS
• Autenticación y visibilidad de páginas
• Analítica y gestores de etiquetas
• Comportamiento de búsqueda
• Scripts y estilos personalizados
• Integraciones de feedback y soporte
• Changelogs
• Metadatos SEO, URLs canónicas y reglas de indexación

Compara tu proyecto migrado con tu inventario de contenido y luego confirma que cada página, versión e idioma previstos se resuelven.

Busca en tus archivos convertidos restos de sintaxis de la plataforma fuente: directivas, importaciones, variables de plantilla, HTML sin procesar e includes sin resolver.

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.