Choisir une méthode
Pour les sites complexes, combinez les deux méthodes. Scrapez votre site public pour créer un
docs.json initial et convertir les composants, puis comparez le résultat avec le référentiel source pour identifier le contenu manquant.
Migrer un site public
docs.json à partir de la navigation publiée.
Une fois le scraper terminé, comparez la navigation Mintlify générée avec votre sidebars.js, sidebars.ts ou une autre structure de navigation Docusaurus. Vérifiez les catégories réduites, les liens externes, les pages d’index de catégorie générées et les pages exclues de la barre latérale publiée.
Migrer depuis les sources
- Votre répertoire de contenu documentaire configuré, qui est
docs/par défaut dans Docusaurus sidebars.js,sidebars.tsou d’autres fichiers de configuration de barre latéraledocusaurus.config.jsoudocusaurus.config.ts- Les fichiers
_category_.json,_category_.ymlou_category_.yaml - Le répertoire
static/et les ressources stockées à côté des pages de documentation versioned_docs/,versioned_sidebars/etversions.json- La documentation localisée sous
i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/, commecurrent/ - Les composants React importés par les pages MDX
Docusaurus peut modifier son répertoire de documentation, son chemin de base de route, son générateur de barre latérale et les fichiers inclus dans la configuration du plugin docs. Selon votre configuration, votre contenu peut se trouver dans un répertoire différent de
docs/.title.
Exemple de frontmatter
docs.json. Convertissez la barre latérale résolue, et non seulement son texte source, si celle-ci utilise des fonctions ou des générateurs personnalisés.
Docusaurus utilise la hiérarchie des fichiers pour les barres latérales générées automatiquement. Mintlify vous permet d’organiser la navigation indépendamment de l’emplacement des fichiers, vous n’avez donc pas besoin de renommer les pages uniquement pour correspondre à la barre latérale.
Convertir le MDX Docusaurus
Les composants React personnalisés ne migrent pas automatiquement depuis votre référentiel source. Déterminez si chaque composant relève du contenu, de la présentation ou du comportement applicatif.
- Remplacez les motifs de contenu par un composant Mintlify.
- Convertissez le contenu répété en snippet réutilisable.
- Ajoutez un composant React lorsque vous avez besoin d’une interaction qu’aucun composant intégré ne fournit.
- Déplacez les pages applicatives complètes en dehors du site de documentation ou reconstruisez-les en tant que mises en page personnalisées.
Préserver les routes et les liens
routeBasePath du plugin docs, le slug du frontmatter de la page, la version et la locale pour créer une URL. Créez un inventaire à partir du sitemap publié plutôt que d’inférer chaque URL à partir des noms de fichiers.
Lorsque vous renommez ou réorganisez une page, ajoutez son ancien chemin publié aux redirections. Testez les liens avec et sans l’ancien chemin de base de route, par exemple /docs/getting-started et /getting-started.
Passez en revue les ID de titres Docusaurus explicites tels que :
Migrer les ressources
static/ et les ressources stockées à côté des pages versionnées. Copiez les deux types dans le référentiel Mintlify.
- Un fichier Docusaurus situé dans
static/img/logo.pngest normalement publié en tant que/img/logo.png. Préservez ce chemin public ou mettez à jour chaque référence. - Résolvez les imports
@site/static/...avant de supprimer les imports Docusaurus. - Conservez les ressources versionnées colocalisées avec la bonne version ou déplacez-les vers des répertoires de ressources spécifiques à la version.
- Vérifiez les images d’arrière-plan CSS et les imports de composants React, qu’un inventaire uniquement Markdown peut manquer.
- 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.
Migrer les versions et les langues
versioned_docs/version-<name> et leur navigation sous versioned_sidebars/. Mappez chaque version maintenue à une version Mintlify. Décidez si current, la dernière version publiée ou une autre version doit être la version par défaut.
Mappez les répertoires de locale Docusaurus à la navigation par langue Mintlify. Préservez le préfixe de locale dans les redirections lorsque l’ancien site utilisait des chemins tels que /fr/docs/....
Si votre référentiel source contenait des pages non publiées ou restreintes, configurez l’authentification et la visibilité des pages, puis testez votre site en tant qu’utilisateur déconnecté et en tant que membre de chaque groupe.
Migrer la documentation d’API
Vérifier votre migration
@theme, @site, :::, DocCardList, useDocusaurusContext et les imports de plugins personnalisés.
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.