Migrer depuis Fern

Migrez un site Fern depuis son référentiel Git. Fern stocke la documentation sous forme de Markdown ou MDX aux côtés de docs.yml, des ressources et des spécifications d’API : le référentiel source est donc plus complet et plus fiable que le HTML publié.

Créez une branche de migration ou une copie de votre référentiel de documentation.

Localisez tous les éléments suivants :

• fern/docs.yml, qui définit les paramètres du site et la navigation
• Les pages MDX, généralement dans fern/docs/pages/
• Les ressources d’image, vidéo, favicon et logo, généralement dans fern/docs/assets/
• Les snippets MDX réutilisables, généralement dans fern/docs/snippets/
• Les entrées de changelog dans fern/docs/changelog/
• fern/styles.css et tout autre CSS ou JavaScript personnalisé
• fern/fern.config.json et la version épinglée du CLI Fern
• Les fichiers de définition OpenAPI, AsyncAPI et Fern
• generators.yml et les scripts qui récupèrent ou génèrent des spécifications d’API
• Les fichiers de configuration de produit, de version et d’onglet référencés par docs.yml
• Les composants MDX personnalisés
• Toute variable d’environnement, spécification distante, fichier généré ou package privé requis lorsque vous exécutez fern check ou fern docs dev

Fern définit la navigation dans docs.yml ou dans des fichiers séparés pour les produits et les versions. Mintlify définit la navigation dans docs.json.

Fern construit les routes à partir des slugs des sections, dossiers, onglets, versions, produits et pages. N’inférez pas l’ancienne URL uniquement à partir du nom de fichier source. Exportez le sitemap publié et résolvez slug, skip-slug et les remplacements de chemin au niveau de la page avant de créer des redirections.

Lorsqu’un dossier Fern utilise index.mdx comme présentation, utilisez cette page comme root du groupe Mintlify. Préservez l’ordre de navigation délibéré plutôt que de vous appuyer sur la découverte alphabétique des dossiers par Fern.

La plupart du Markdown et du MDX standard peut être déplacé directement. Chaque page Mintlify nécessite un title. Conservez les descriptions, les mots-clés et les autres métadonnées SEO utiles.

Passez en revue le frontmatter spécifique à Fern tel que :

• slug et les remplacements de chemin
• Les badges availability
• Les paramètres de mise en page et de table des matières
• Les contrôles de visibilité et d’indexation
• Les associations de référence API

Recréez le comportement avec le frontmatter, la navigation ou le contenu Mintlify. Ajoutez un callout pour les états de disponibilité qui n’ont pas de présentation équivalente.

Fern et Mintlify utilisent tous deux des composants MDX, mais les noms et les propriétés des composants ne sont pas interchangeables. Recherchez sur chaque page les balises JSX et les imports plutôt que de supposer qu’ils s’affichent sans modification.

Supprimez les imports propres à Fern après la conversion. Prévisualisez les pages qui utilisent des composants imbriqués, car la syntaxe valide et les propriétés prises en charge peuvent différer même lorsque les deux plateformes utilisent le même nom de composant.

Utilisez votre spécification d’API pour créer vos nouvelles pages de référence API.

1. Retracez chaque entrée de navigation api jusqu’à sa source OpenAPI, AsyncAPI ou de définition Fern.
2. Téléchargez les spécifications que le build récupère depuis une URL ou un autre référentiel.
3. Préservez les overlays, les exemples générés, la configuration d’authentification et la prose personnalisée des endpoints.
4. Ajoutez la spécification source au référentiel Mintlify et configurez les pages de référence API.
5. Comparez le regroupement des endpoints, les serveurs, les schémas de sécurité, les exemples et les snippets SDK avec le site Fern.

Les définitions Fern peuvent contenir des informations qui ne sont pas représentées directement dans un document OpenAPI. Vérifiez la sortie OpenAPI générée et déplacez toute description ou exemple manquant avant de retirer votre build Fern.

Fern peut placer la navigation dans des fichiers YAML spécifiques à un produit ou à une version. Inventoriez chaque fichier référencé et mappez chaque produit et version maintenue à la structure de navigation Mintlify correspondante.

Vérifiez :

• Une page d’accueil en dehors de la navigation du produit
• Des produits ou versions avec des arborescences de pages différentes
• Des slugs ajoutés par niveaux de produit, de version ou d’onglet
• Des spécifications d’API spécifiques à une version
• Des sections cachées, dépréciées ou en pré-version
• Des produits externes qui pointent vers un autre site

Copiez les fichiers depuis les répertoires de ressources configurés et mettez à jour les chemins relatifs après avoir déplacé les pages. Ne laissez pas de ressources de production requises sur votre ancien déploiement, sauf si vous prévoyez de conserver cet hébergement après la migration. Examinez docs.yml pour les logos, les favicons, les images sociales, les polices, les couleurs, les liens de la barre de navigation, les bannières d’annonce, les redirections, l’analytique, le CSS personnalisé et le JavaScript personnalisé.

Recréez les paramètres pris en charge dans docs.json. Traitez le CSS et le JavaScript comme des exigences à évaluer, et non comme des fichiers à copier aveuglément, car leurs sélecteurs et leurs hypothèses d’exécution sont spécifiques à la plateforme.

Comparez chaque entrée de navigation docs.yml et chaque page de dossier découverte à docs.json, puis validez chaque produit, version et onglet.

Recherchez dans vos fichiers convertis toute syntaxe Fern résiduelle : imports de composants, propriétés JSX non prises en charge et blocs Versions ou If.

Lancez votre nouveau site

• Instaurez un gel de contenu sur votre ancien site et suivez chaque modification qui y est apportée après votre instantané de migration.
• Confirmez votre branche de production et votre référentiel sur la page Paramètres Git de votre tableau de bord.
• Notez vos enregistrements DNS existants et gardez votre ancien site en ligne jusqu’à ce que vous ayez vérifié que votre déploiement Mintlify est actif.
• Vérifiez la barre de navigation, le pied de page, le favicon, le logo, les couleurs et la typographie.
• Vérifiez les métadonnées du site et des pages, les URL canoniques et les préférences d’indexation. Voir Paramètres SEO et de recherche.
• Installez toutes les intégrations d’analytique requises, et ajoutez éventuellement une page 404 personnalisée.
• Si vous avez migré une référence API, comparez les pages d’endpoints, la structure de navigation, les URL de serveur, les schémas d’authentification et les exemples avec votre ancien site.
• Prévisualisez votre commit de lancement exact dans un déploiement de prévisualisation. Vérifiez les mises en page desktop et mobile, les pages de chaque section de navigation, la recherche et vos redirections.
• Vérifiez la console du navigateur et l’onglet réseau pour détecter d’éventuelles erreurs sur les pages qui utilisent des composants ou des scripts personnalisés.
• Basculez votre domaine avec le guide sur les domaines personnalisés, qui couvre la bascule sans interruption pour un domaine qui sert déjà de la documentation.
• Après le lancement, surveillez les erreurs 404, les échecs de redirection et les échecs de build.

• Structure du projet
• Navigation
• Produits
• Versions
• Composants
• CSS et JavaScript personnalisés
• Commandes CLI