Migrer depuis Document360

Exportez un projet Document360 au format ZIP, puis convertissez ses espaces de travail, langues, catégories et articles en un projet Mintlify. Utilisez l’API Document360 et le site publié pour auditer le contenu que l’export ne représente peut-être pas complètement. Avant d’exporter, créez une sauvegarde manuelle nommée dans Document360. Accédez à Settings > Knowledge base portal > Backup & Restore. Téléchargez un export de projet pour la migration elle-même. Dans Document360, accédez à Content tools > Import and export > Import and export project.

1. Cliquez sur Export project.
2. Sélectionnez le format d’export. Choisissez JSON pour un export de projet complet.
3. Dans Include new or modified articles in, sélectionnez All afin que l’export ne soit pas limité aux articles récemment modifiés.
4. Sélectionnez chaque espace de travail, langue, catégorie et sous-catégorie maintenu.
5. Sélectionnez Include media files.
6. Cliquez sur Export. L’export s’exécute en arrière-plan et vous informe lorsqu’il est prêt.
7. Téléchargez le ZIP depuis Recent files dès qu’il est prêt. Chaque nouvel export écrase le ZIP précédent.
8. Exportez la liste All articles au format CSV. Cette liste de métadonnées est utile pour rapprocher les titres, le statut de publication, les dates, les catégories et les URL.

Notez les fonctionnalités du projet qui nécessitent un travail de migration séparé.

• Contenu et navigation du Homepage Builder
• Pages personnalisées liées depuis l’en-tête, le pied de page ou la barre latérale
• Snippets, variables, termes de glossaire et modèles
• CSS, JavaScript et intégrations personnalisés
• Groupes de lecteurs, rôles, SSO et règles de contenu privé
• Règles de redirection et domaines personnalisés
• Configuration de l’analytique, des retours, des formulaires et de la recherche
• Spécifications sources de référence API
• Fichiers Drive, arbres de décision et contenu intégré

Utilisez le sitemap publié et l’API Customer de Document360 pour comparer l’export au contenu public et privé. L’API est particulièrement utile lorsque vous devez parcourir les métadonnées de catégorie ou récupérer des champs difficiles à dériver des fichiers exportés. Mappez la hiérarchie Document360 à docs.json. Choisissez le mappage des espaces de travail en fonction de la manière dont vos lecteurs les utilisent. Un espace de travail nommé v1 est généralement une version, tandis que des bases de connaissances de produits distinctes peuvent mieux correspondre à des produits ou à des onglets. Voir Navigation pour plus d’informations sur les éléments de navigation Mintlify. Les réponses de l’API de catégorie Document360 n’incluent que les enfants directs. Si vous utilisez l’API pour créer un inventaire, demandez chaque catégorie enfant de manière récursive et récupérez le contenu séparément pour les catégories d’index et de page. Copiez les articles Markdown dans des fichiers .mdx et convertissez le HTML ou JSON exporté en MDX. Ajoutez un frontmatter contenant au moins un title, et conservez les descriptions, mots-clés, métadonnées de publication et routes canoniques lorsque cela est utile. Passez en revue la sortie spécifique à la plateforme de chaque éditeur : Document360 et Mintlify affichent tous deux le title du frontmatter comme H1 de la page, donc les corps de page commencent au H2. N’ajoutez pas de H1 en double pendant la conversion. Inventoriez les variables, snippets, termes de glossaire et chaque utilisation avant de les remplacer.

• Convertissez les blocs de contenu réutilisables en snippets Mintlify.
• Remplacez les variables par du texte explicite, du contenu généré ou une autre source de vérité maintenable.
• Remplacez les infobulles de glossaire par des liens ou des composants d’infobulle pris en charge.
• Préservez les variations spécifiques à chaque langue plutôt que de consolider un texte qui ne semble identique que dans une seule locale.

Vérifiez le site source rendu ainsi que l’export pour déterminer si chaque élément réutilisable apparaît sous forme de contenu développé ou de référence spécifique à la plateforme. Téléchargez le fichier OpenAPI original de chaque catégorie de référence API Document360 ou récupérez-le depuis le système qui synchronise la spécification.

1. Ajoutez la spécification originale au référentiel Mintlify.
2. Configurez des pages générées par OpenAPI.
3. Préservez les descriptions ou exemples d’endpoints personnalisés que les éditeurs ont ajoutés après l’import.
4. Comparez la hiérarchie des tags, l’ordre des endpoints, les serveurs, l’authentification, les exemples et les échantillons de code.
5. Remplacez toute automatisation de resynchronisation Document360 par le workflow de déploiement Mintlify.

Ne convertissez pas les articles d’endpoints générés lorsque la spécification source est disponible. Incluez les médias dans l’export du projet et copiez les fichiers dont vous êtes propriétaire dans votre référentiel de projet Mintlify. Vérifiez les liens Document360 Drive, les vignettes, les SVG, les fichiers téléchargeables, les images d’arrière-plan CSS et le contenu intégré depuis des services externes. Mettez à jour les chemins de ressources après avoir réorganisé les pages. Ne laissez pas de ressources de production requises sur les domaines Document360, sauf si vous comptez maintenir cet hébergement actif. Les routes Document360 peuvent inclure des slugs d’espace de travail et de langue, ainsi que des slugs de catégorie et d’article. Construisez une carte d’URL à partir du sitemap publié et du CSV d’articles exporté, puis ajoutez des redirections pour chaque route modifiée. Recréez la documentation privée avec l’authentification et le contrôle d’accès. Créez des groupes de lecteurs et des restrictions basées sur les rôles qui reflètent votre configuration de contrôle d’accès précédente. Testez en tant que chaque groupe avant de publier votre site. Vérifiez que votre ZIP exporté, votre CSV d’articles, votre inventaire d’API et votre sitemap publié sont alignés, puis testez le changement de langue et chaque sélecteur d’espace de travail. Recherchez dans vos fichiers convertis tout contenu Document360 non converti : HTML brut, références de snippets et de variables, notes privées et embeds de widgets.

​

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.

• Exporter un ZIP de projet
• Exporter tous les articles
• Sauvegarde et restauration
• Espaces de travail et langues
• Éditeur Markdown
• Snippets
• Gérer les références API
• API de catégorie
• Pages personnalisées