Migrer depuis Docusaurus

Migrez un site public Docusaurus 2 ou 3 avec le scraper Mintlify. Si vous avez besoin d’un contrôle plus précis sur les versions, le contenu localisé ou les composants React personnalisés, migrez depuis votre référentiel source.

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.

mkdir mintlify-migration
cd mintlify-migration
npx @mintlify/scraping@latest section https://docs.example.com

Si votre documentation Docusaurus utilise un chemin de base de route, appliquez un filtre pour scraper ce chemin :

npx @mintlify/scraping@latest section https://example.com --filter=/docs

Le scraper détecte Docusaurus, développe sa barre latérale, télécharge les images accessibles, convertit les composants rendus courants en composants Mintlify et crée un 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.

Copiez le contenu source suivant dans une branche de migration distincte ou un répertoire de travail.

• Votre répertoire de contenu documentaire configuré, qui est docs/ par défaut dans Docusaurus
• sidebars.js, sidebars.ts ou d’autres fichiers de configuration de barre latérale
• docusaurus.config.js ou docusaurus.config.ts
• Les fichiers _category_.json, _category_.yml ou _category_.yaml
• Le répertoire static/ et les ressources stockées à côté des pages de documentation
• versioned_docs/, versioned_sidebars/ et versions.json
• La documentation localisée sous i18n/<locale>/docusaurus-plugin-content-docs/<versionName>/, comme current/
• Les composants React importés par les pages MDX

Copiez les pages Markdown et MDX dans votre projet Mintlify. Chaque page nécessite un frontmatter contenant au moins un title.

---
title: "Get started"
description: "Install the SDK and make your first request."
---

Les barres latérales Docusaurus sont du JavaScript ou TypeScript exécutable, tandis que la navigation Mintlify est une donnée dans 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.

Le Markdown standard fonctionne généralement sans modification. Passez en revue la syntaxe et les imports spécifiques à 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.

Docusaurus combine le 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 :

## Configure the client {/* #configure-client */}

Convertissez-les en syntaxe d’ID de titre personnalisé Mintlify lorsque vous devez préserver les liens d’ancrage entrants :

## Configure the client [#configure-client]

Docusaurus prend en charge les ressources globales dans 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.png est 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.

Docusaurus stocke les versions figées sous 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.

Localisez les fichiers OpenAPI ou AsyncAPI référencés par les plugins, les pages personnalisées ou les scripts de build. Ajoutez la spécification originale au référentiel Mintlify et configurez des pages générées par OpenAPI. Ne migrez pas le HTML rendu des endpoints lorsque la spécification source est disponible.

Comparez vos pages migrées à vos entrées de barre latérale et à votre sitemap publié, puis prévisualisez chaque version et chaque langue maintenue.

Recherchez dans vos fichiers convertis toute syntaxe Docusaurus résiduelle, qui apparaît sous forme de texte littéral ou fait échouer le build : @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.

• Configuration du plugin docs
• Barres latérales
• Gestion des versions
• Internationalisation
• Ressources statiques
• ID de titres