Skip to main content
Utilisez une migration manuelle lorsque votre plateforme actuelle ne figure pas dans les plateformes listées, que votre site est privé ou que vous avez besoin d’un contrôle complet sur la structure résultante.

​
Rassembler votre contenu source

Exportez ou copiez tout le contenu avant de le convertir.
  1. Les fichiers Markdown ou MDX de votre référentiel source
  2. Un export natif Markdown ou HTML depuis votre plateforme actuelle
  3. Le contenu récupéré via l’API de votre plateforme actuelle
  4. Le HTML rendu depuis votre site publié
  5. La copie et la conversion manuelles
Conservez votre export original inchangé. Effectuez le travail de conversion dans une copie afin de pouvoir comparer ou redémarrer votre migration. Créez un inventaire contenant l’identifiant source, le titre, l’URL publiée, le chemin de destination, le type de contenu, la version, la langue et le statut de migration de chaque page. Incluez les pages non publiées qui doivent rester disponibles.

​
Créer votre projet Mintlify

Un projet Mintlify typique comprend :
  • Un fichier docs.json pour les paramètres du site et la navigation
  • Des fichiers Markdown ou MDX pour les pages qui ne sont pas générées à partir d’une spécification d’API
  • Des images et des fichiers téléchargeables que vous souhaitez héberger depuis votre référentiel
  • Des spécifications OpenAPI ou AsyncAPI facultatives, ou des schémas GraphQL pour la documentation d’API générée
Voir Pages pour connaître le frontmatter pris en charge et le comportement des fichiers.

​
Concevoir votre navigation

Vous pouvez reproduire fidèlement votre structure de navigation existante ou profiter de la migration comme d’une opportunité pour améliorer la façon dont les utilisateurs trouvent le contenu. Utilisez une structure de navigation appropriée. Le tableau suivant montre les motifs de navigation courants pour les sites hébergés sur Mintlify. Ajoutez chaque chemin de page à docs.json sauf si vous prévoyez de masquer la page. Une page masquée reste accessible par URL, mais elle est exclue par défaut de la recherche du site, des sitemaps, de l’indexation par les moteurs de recherche et du contexte IA.

​
Convertir votre contenu

Le Markdown ordinaire nécessite généralement peu de conversion. Remplacez la syntaxe spécifique à la plateforme par des composants Mintlify. Recherchez dans vos fichiers convertis les directives, imports, variables de templating, HTML brut et includes non résolus de la plateforme source. Ces motifs s’affichent souvent sous forme de texte ou font échouer un build MDX.

​
Migrer la documentation d’API

Localisez la spécification OpenAPI ou AsyncAPI originale ou le schéma GraphQL lorsqu’il en existe un. Ajoutez le fichier source à votre référentiel Mintlify et suivez le guide de configuration correspondant. Si votre plateforme source stockait les descriptions d’endpoints en dehors de la spécification, fusionnez le contenu utile dans la spécification ou placez-le dans des guides adjacents. Comparez l’ordre des opérations, l’authentification, les URL de serveur, les exemples, les schémas et les échantillons de code avec votre ancien site. Vous pouvez générer des pages d’endpoints OpenAPI initiales avec le package scraper Mintlify :

​
Migrer vos ressources

Copiez les images, vidéos, polices et fichiers téléchargeables dont vous êtes propriétaire dans votre référentiel. Préservez les chemins publics existants lorsque cela est pratique afin de réduire les changements de liens. Passez en revue les motifs suivants pour identifier les ressources qui doivent être migrées.
  • Destinations des images et des liens Markdown
  • Éléments HTML <img> et <video>
  • Images d’arrière-plan CSS
  • Ressources référencées par des composants importés
  • Fichiers hébergés par votre ancien fournisseur de documentation
  • Ressources spécifiques à une version et à une langue
Ne laissez pas de ressources de production requises sur le domaine de votre ancien fournisseur, sauf si vous prévoyez de conserver cet hébergement après la migration.

​
Préserver les URL

Créez un mappage de chaque ancienne URL publiée vers sa destination. Ajoutez une redirection chaque fois que le pathname change. Incluez les motifs suivants dans votre mappage de redirection.
  • Pages supprimées ou consolidées lors de la migration
  • Préfixes de version et de langue
  • Préfixes de catégorie ou d’espace
  • Pages d’accueil personnalisées
  • Pages d’endpoints d’API
  • Slugs explicites et anciens alias

​
Recréer les fonctionnalités de votre site

Les exports de contenu n’incluent normalement pas la configuration de la plateforme. Inventoriez et recréez les fonctionnalités dont vous avez encore besoin.
  • Domaine personnalisé et DNS
  • Authentification et visibilité des pages
  • Analytique et gestionnaires de balises
  • Comportement de la recherche
  • Scripts et styles personnalisés
  • Intégrations de retours et de support
  • Changelogs
  • Métadonnées SEO, URL canoniques et règles d’indexation

​
Vérifier votre migration

Comparez votre projet migré à votre inventaire de contenu, puis vérifiez que chaque page, version et langue prévue se résout. Recherchez dans vos fichiers convertis toute syntaxe de la plateforme source résiduelle : directives, imports, variables de templating, HTML brut et includes non résolus.

​
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.

Sujets connexes

Migrer depuis Document360Migrer depuis FernPages