Migrar desde Fern

Migra un sitio de Fern desde su repositorio Git. Fern almacena la documentación como Markdown o MDX junto con docs.yml, recursos y especificaciones de API, por lo que el repositorio fuente es más completo y fiable que el HTML publicado. Crea una rama de migración o una copia de tu repositorio de documentación. Localiza todos los siguientes elementos:

• fern/docs.yml, que define la configuración del sitio y la navegación
• Páginas MDX, habitualmente en fern/docs/pages/
• Recursos de imagen, video, favicon y logotipo, habitualmente en fern/docs/assets/
• Snippets MDX reutilizables, habitualmente en fern/docs/snippets/
• Entradas del changelog en fern/docs/changelog/
• fern/styles.css y cualquier otro CSS o JavaScript personalizado
• fern/fern.config.json y la versión fijada del CLI de Fern
• Archivos de OpenAPI, AsyncAPI y de definición de Fern
• generators.yml y los scripts que obtienen o generan especificaciones de API
• Archivos de configuración de productos, versiones y pestañas referenciados por docs.yml
• Componentes MDX personalizados
• Cualquier variable de entorno, especificación remota, archivos generados o paquetes privados requeridos al ejecutar fern check o fern docs dev

Fern define la navegación en docs.yml o en archivos separados para productos y versiones. Mintlify define la navegación en docs.json. Fern construye las rutas a partir de los slugs de secciones, carpetas, pestañas, versiones, productos y páginas. No infieras la URL antigua solo a partir del nombre de archivo fuente. Exporta el sitemap publicado y resuelve los overrides de slug, skip-slug y de ruta a nivel de página antes de crear las redirecciones. Cuando una carpeta de Fern utilice index.mdx como resumen, usa esa página como root del grupo de Mintlify. Conserva el orden de navegación intencionado en lugar de basarte en el descubrimiento alfabético de carpetas de Fern. La mayor parte del Markdown y MDX estándar puede migrarse directamente. Cada página de Mintlify necesita un title. Conserva las descripciones, palabras clave y otros metadatos SEO útiles. Revisa el frontmatter específico de Fern, como:

• slug y overrides de ruta
• Insignias de availability
• Configuración del diseño de página y de la tabla de contenidos
• Controles de visibilidad e indexación
• Asociaciones con la referencia de API

Recrea el comportamiento con frontmatter, navegación o contenido de Mintlify. Añade un callout para los estados de disponibilidad que no tengan una presentación equivalente. Fern y Mintlify usan ambos componentes MDX, pero los nombres y propiedades de los componentes no son intercambiables. Busca etiquetas JSX e importaciones en cada página en lugar de asumir que se renderizan sin cambios. Elimina las importaciones exclusivas de Fern después de la conversión. Previsualiza las páginas que usen componentes anidados, porque la sintaxis válida y las propiedades compatibles pueden diferir aunque ambas plataformas usen el mismo nombre de componente. Usa tu especificación de API para crear tus nuevas páginas de referencia de API.

1. Rastrea cada entrada de navegación api hasta su origen en OpenAPI, AsyncAPI o en la definición de Fern.
2. Descarga las especificaciones que la compilación obtiene desde una URL u otro repositorio.
3. Conserva los overlays, ejemplos generados, la configuración de autenticación y la prosa personalizada de los endpoints.
4. Añade la especificación fuente al repositorio de Mintlify y configura las páginas de referencia de API.
5. Compara la agrupación de endpoints, los servidores, los esquemas de seguridad, los ejemplos y los snippets de SDK con el sitio de Fern.

Las definiciones de Fern pueden contener información que no se representa directamente en un documento OpenAPI. Revisa la salida OpenAPI generada y traslada las descripciones o ejemplos que falten antes de retirar tu compilación de Fern. Fern puede colocar la navegación en archivos YAML específicos de un producto o de una versión. Inventaría cada archivo referenciado y asocia cada producto y versión mantenidos a la estructura de navegación correspondiente de Mintlify. Comprueba:

• Una página de aterrizaje fuera de la navegación del producto
• Productos o versiones con árboles de páginas distintos
• Slugs añadidos por niveles de producto, versión o pestaña
• Especificaciones de API específicas por versión
• Secciones ocultas, obsoletas o preliminares
• Productos externos que enlazan a otro sitio

Copia los archivos desde los directorios de recursos configurados y actualiza las rutas relativas después de mover las páginas. No dejes recursos requeridos en producción en tu despliegue anterior a menos que planees mantener ese hosting después de la migración. Revisa docs.yml para logotipos, favicons, imágenes sociales, fuentes, colores, enlaces de la barra de navegación, banners de anuncios, redirecciones, analítica, CSS personalizado y JavaScript personalizado. Recrea los ajustes compatibles en docs.json. Trata el CSS y JavaScript como requisitos a evaluar, no como archivos para copiar sin más, porque sus selectores y suposiciones en tiempo de ejecución son específicos de la plataforma. Compara cada entrada de navegación de docs.yml y cada página de carpeta descubierta con docs.json, luego valida cada producto, versión y pestaña. Busca en tus archivos convertidos restos de sintaxis de Fern: importaciones de componentes, propiedades JSX no compatibles y bloques Versions o If.

​

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.

• Estructura del proyecto
• Navegación
• Productos
• Versiones
• Componentes
• CSS y JavaScript personalizados
• Comandos del CLI