Para una migración completa, empieza con una exportación nativa y utiliza un scrape de tu sitio público como comparación. Los dos inventarios ayudan a descubrir las páginas no publicadas y el contenido que no tiene una representación en archivo.
Desde el menú de rama en ReadMe, exporta los archivos de documentación como un ZIP. ReadMe envía la exportación completada por correo electrónico. La estructura del proyecto exportado puede incluir guías, recetas, páginas personalizadas, bloques personalizados, contenido de API Reference y archivos OpenAPI, pero no incluye los archivos de imagen en sí.
Si tu proyecto usa la integración de GitHub de ReadMe, puedes exportar tu proyecto a un repositorio. ReadMe documenta que el repositorio contiene el mismo contenido que una exportación de rama y puede incluir todas las versiones de la documentación.
Mantén tu exportación sin cambios como una instantánea de migración. Realiza el trabajo de conversión en una copia o en una rama de Git separada.
-p puppeteer instala Puppeteer, que el scraper usa para renderizar el sitio en un navegador. Sin Puppeteer, el scraper obtiene las páginas sin navegador y la navegación generada puede quedar incompleta.
Si tu sitio contiene documentación bajo una ruta o versión específica, usa un filtro para limitar la migración inicial:
index.md para la página padre y _order.yaml para sus hijas. Traduce esa estructura a entradas anidadas de group y pages en docs.json. Utiliza el index.md padre como root del grupo cuando contenga contenido útil de resumen.
Consulta Navegación para más información sobre cómo estructurar los elementos de navegación.
Conserva
title, los metadatos SEO, las descripciones y las palabras clave útiles. Convierte los campos específicos de ReadMe.
ReadMe admite un dialecto de Markdown personalizado y bloques mágicos basados en JSON. El scraper convierte los componentes renderizados comunes, pero las exportaciones de archivos pueden conservar la sintaxis de la plataforma. Revisa los siguientes patrones para identificar contenido que debe convertirse.
- Callouts, pestañas, acordeones, tarjetas y grupos de código
- Contenido reutilizable y bloques personalizados
- Variables y términos del glosario
- Recetas interactivas
- Páginas HTML personalizadas
- Exploradores de API integrados y contenido personalizado
- Encuentra cada archivo OpenAPI en JSON o YAML en
reference/y en cualquier repositorio fuente que hayas usado conrdmeo con la sincronización de API de ReadMe. - Identifica el Markdown que los editores añadieron en ReadMe fuera de la especificación. ReadMe asocia este contenido con una operación por su
operationId. - Añade la especificación a tu repositorio de Mintlify y configura las páginas generadas a partir de OpenAPI.
- Traslada el Markdown complementario valioso a la descripción de la operación correspondiente, la descripción del esquema o una guía adyacente.
- Compara la autenticación, las URL de servidor, los ejemplos de código, los ejemplos y el orden de los endpoints con tu referencia original.
- Una versión predeterminada distinta y su comportamiento de URL
- Versiones ocultas, beta y obsoletas
- Contenido reutilizable específico de una versión
- Páginas que existen solo en una versión
- Especificaciones de API que difieren según la versión
- Páginas personalizadas o contenido de changelog compartidos
files.readme.io). Descarga esos archivos y súbelos a tu repositorio de Mintlify antes de salir en vivo.
Para descargar todos los recursos referenciados desde una exportación:
- Desde la raíz de tu exportación descomprimida, extrae las URL de los recursos del Markdown:
- Descarga cada archivo en un directorio
images/de tu repositorio de Mintlify: - Actualiza las referencias del Markdown para que apunten a las nuevas rutas locales (por ejemplo, reemplaza
https://files.readme.io/abc123-diagram.pngpor/images/abc123-diagram.png).
/docs/, /reference/ o /page/. Exporta un sitemap o rastrea tu sitio publicado para capturar las rutas reales.
Añade redirecciones para cada ruta que cambie. Presta especial atención a:
- URL de la versión predeterminada que omiten el segmento de versión
- Páginas personalizadas bajo
/page - Guías y páginas de referencia con el mismo slug
- Rutas de endpoint derivadas de las etiquetas y resúmenes de OpenAPI
- Páginas obsoletas u ocultas que aún reciben tráfico
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 sitio 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.