- Archivos Markdown o MDX de tu repositorio fuente
- Una exportación nativa en Markdown o HTML desde tu plataforma actual
- Contenido obtenido a través de la API de tu plataforma actual
- HTML renderizado desde tu sitio publicado
- Copia y conversión manuales
- Un archivo
docs.jsonpara 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
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.
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:
- 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
- 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
- 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
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.