Migrar desde ReadMe

Migra un proyecto público de ReadMe con el scraper de Mintlify, o exporta los archivos del proyecto desde ReadMe cuando necesites contenido privado, especificaciones OpenAPI o múltiples versiones.

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.

mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://your-project.readme.io

Si tu sitio contiene documentación bajo una ruta o versión específica, usa un filtro para limitar la migración inicial:

npx @mintlify/scraping@latest section https://your-project.readme.io --filter=/docs

El scraper convierte las páginas alcanzables, las imágenes, la navegación y los componentes renderizados comunes. No puede acceder a tu contenido privado o no publicado y no sustituye a una exportación separada de tu especificación OpenAPI fuente.

La estructura de archivos de ReadMe normalmente separa el contenido por tipo.

docs/             Guías organizadas por categoría
reference/        Páginas de referencia de API y archivos OpenAPI
recipes/          Recetas paso a paso
custom_pages/     Páginas personalizadas en Markdown o HTML
custom_blocks/    Bloques personalizados reutilizables
_order.yaml       Orden dentro de una carpeta o categoría

Una carpeta que contenga páginas hijas puede incluir 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

Convierte el material reutilizable en snippets de Mintlify. Tu exportación podría expandir un bloque reutilizable en cada página, así que compara las copias y consolida solo el contenido idéntico.

Prefiere tu archivo OpenAPI original a las páginas de endpoints renderizadas o exportadas.

1. Encuentra cada archivo OpenAPI en JSON o YAML en reference/ y en cualquier repositorio fuente que hayas usado con rdme o con la sincronización de API de ReadMe.
2. 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.
3. Añade la especificación a tu repositorio de Mintlify y configura las páginas generadas a partir de OpenAPI.
4. Traslada el Markdown complementario valioso a la descripción de la operación correspondiente, la descripción del esquema o una guía adyacente.
5. 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.

ReadMe también puede ingerir Swagger 2.0 y colecciones de Postman. Recupera la fuente OpenAPI convertida u original antes de configurar Mintlify en lugar de copiar la referencia renderizada.

Las versiones y ramas de ReadMe se aplican al contenido de Guías, Recetas y API Reference, mientras que parte del contenido de tu proyecto permanece compartido entre versiones. Inventaría cada versión por separado y asocia las versiones mantenidas a la navegación de versiones de Mintlify.

Revisa los siguientes patrones.

• 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

Tu exportación ZIP de ReadMe no contiene las imágenes alojadas. El Markdown exportado las referencia por su URL alojada original (normalmente en 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:

1. Desde la raíz de tu exportación descomprimida, extrae las URL de los recursos del Markdown:

   grep -rhoE 'https://files\.readme\.io/[^)"\s]+' . | sort -u > asset-urls.txt

2. Descarga cada archivo en un directorio images/ de tu repositorio de Mintlify:

   mkdir -p images && cd images && wget -i ../asset-urls.txt

3. Actualiza las referencias del Markdown para que apunten a las nuevas rutas locales (por ejemplo, reemplaza https://files.readme.io/abc123-diagram.png por /images/abc123-diagram.png).

Para las imágenes o archivos que no estén enlazados desde la exportación (por ejemplo, recursos adjuntos solo a Custom Pages o referenciados desde bloques mágicos JSON), usa la API de ReadMe para enumerarlos y descargarlos.

No dependas de las URL de recursos remotos de ReadMe para tu sitio final. Copia los archivos que te pertenezcan, actualiza sus referencias y verifica el texto alternativo y los enlaces a archivos descargables.

Tus URL de ReadMe pueden incluir la versión del proyecto y el tipo de contenido, como /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

Compara tu exportación en ZIP, el inventario obtenido por API y el sitemap publicado con tus archivos migrados, y previsualiza cada versión mantenida.

Busca en tus archivos convertidos restos de sintaxis de ReadMe: bloques mágicos, variables, referencias al glosario y directivas de Custom Block.

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.

• Exportar datos
• Estructura de la documentación
• Versionado
• Compatibilidad con OpenAPI
• Contenido reutilizable