Migrer Docusaurus vers Astro Starlight

Pourquoi Migrer de Docusaurus vers Astro Starlight

Docusaurus a bien servi l'écosystème de documentation React. Les équipes pouvaient mettre en place des sites de documentation avec versioning, recherche et support MDX assez rapidement. Mais il expédie un runtime React complet à chaque visiteur, et ce poids se voit dans chaque audit Lighthouse.

Astro Starlight est conçu spécifiquement pour la documentation. Il génère du HTML statique par défaut, n'expédie zéro JavaScript à moins que vous ne l'activiez explicitement, et inclut la recherche intégrée, la navigation de barre latérale et l'i18n prêts à l'emploi. Vos fichiers MDX se transfèrent directement. L'équipe d'Astro maintient bien le chemin de migration documenté.

Si votre site Docusaurus semble lent sur mobile, si les temps de build s'allongent au fur et à mesure que votre documentation grandit, ou si vous êtes fatigué de combattre les problèmes d'hydratation React sur ce qui devrait être du contenu statique — Starlight résout tout cela.

Les Vrais Problèmes de Docusaurus à Grande Échelle

Surcharge JavaScript Côté Client

Docusaurus expédie React au navigateur. Chaque chargement de page inclut le runtime React, React DOM et la couche de routage côté client. Pour un site de documentation où 99% des pages sont du texte statique et des blocs de code, c'est du poids mort. Les scores Lighthouse mobiles atterrissent généralement entre 45-65 à cause de cela.

Dégradation des Performances de Build

Au fur et à mesure que votre collection de documents grandit au-delà de quelques centaines de pages, les builds Docusaurus ralentissent notablement. Le bundling Webpack aggrave les choses. Les équipes avec 500+ pages de documentation signalent des temps de build dépassant 5 minutes, ce qui tue les boucles de rétroaction CI/CD.

Verrouillage de l'Écosystème de Plugins

Les plugins Docusaurus sont étroitement couplés à son architecture interne. Besoin de plugins remark personnalisés ? Ils fonctionnent, mais la couche de configuration ajoute de la complexité. Voulez-vous changer le fournisseur de recherche ? Vous travaillez dans le système de présets de Docusaurus, qui contraint ce qui est possible.

Rigidité de la Configuration de la Barre Latérale

Les configs de barre latérale Docusaurus utilisent un schéma spécifique JSON/JS avec les champs category, items et type. Cela fonctionne, mais la configuration devient difficile à gérer pour les grands arbres de documentation avec un nesting profond. Réorganiser les sections signifie éditer les fichiers de configuration plutôt que de simplement déplacer les fichiers.

Dépendances des Composants React

Les composants personnalisés dans Docusaurus sont des composants React qui s'hydratent sur le client. Si vous avez construit des exemples interactifs, du contenu en onglets ou des admonitions personnalisées, ils portent tous le coût d'hydratation React — même quand l'interactivité est minimale.

Ce que Astro Starlight Vous Offre

Zéro-JS par Défaut

Starlight génère du HTML et CSS purement statiques. Aucun runtime de framework n'est expédié au navigateur à moins que vous n'ajoutiez explicitement une île interactive. Les pages de documentation se chargent en moins de 200ms sur les connexions 3G. Les scores Lighthouse atteignent 95-100 régulièrement.

Compatibilité MDX

Starlight inclut l'intégration MDX d'Astro par défaut. Vos fichiers .mdx existants fonctionnent immédiatement. Les champs de frontmatter se mappent proprement — title, description, sidebar_label ont tous des équivalents Starlight. Les plugins remark et rehype se transfèrent sans modifications.

Recherche Pagefind Intégrée

Starlight est livré avec Pagefind, un moteur de recherche statique qui indexe votre HTML construit et s'exécute entièrement dans le navigateur. Aucun service externe, aucune clé API, aucun délai de crawl Algolia. La recherche fonctionne hors ligne et ajoute environ 10KB à votre bundle. Pour les équipes qui ont spécifiquement besoin d'Algolia, il y a un plugin Starlight officiel pour DocSearch.

Génération de Barre Latérale Basée sur les Fichiers

Starlight peut générer automatiquement des barres latérales à partir de votre structure de fichiers. Déposez un fichier MDX dans un dossier, il apparaît dans la barre latérale. Vous pouvez toujours l'écraser avec une configuration explicite, mais le comportement par défaut élimine la plupart de la maintenance de la config de barre latérale.

Collections de Contenu avec Sécurité des Types

Starlight utilise les collections de contenu d'Astro, qui valident votre frontmatter par rapport à un schéma Zod au moment du build. Les fautes de frappe dans les champs de frontmatter sont détectées avant le déploiement, et non découvertes par les utilisateurs.

Notre Processus de Migration

Phase 1 : Audit et Planification

Nous commençons par inventorier votre site Docusaurus — nombre de pages, composants personnalisés, utilisation de plugins, structure de barre latérale, configuration de versioning et toute personnalisation de thème. Nous mappons chaque fonctionnalité Docusaurus à son équivalent Starlight et signalons les lacunes qui nécessitent des solutions personnalisées.

Phase 2 : Échafaudage Starlight

Nous créons un nouveau projet Starlight en utilisant yarn create astro --template starlight et le configurons pour correspondre à la structure de votre site existant. Nous configurons les collections de contenu, configurons le astro.config.mjs et établissons la hiérarchie des dossiers qui reflète votre structure d'URL actuelle.

Phase 3 : Migration de Contenu

Les fichiers MDX se transfèrent avec des modifications minimales. Nous gérons :

• Remappage du frontmatter : Les champs spécifiques à Docusaurus comme sidebar_position, sidebar_label et slug sont convertis au schéma de frontmatter de Starlight
• Mises à jour des déclarations d'import : Les imports de composants changent des chemins Docusaurus aux chemins des composants Astro
• Syntaxe des admonitions : Docusaurus utilise la syntaxe :::note ; Starlight utilise des composants <Aside> ou sa propre syntaxe d'admonition
• Composants Tab : <Tabs> et <TabItem> de Docusaurus sont remplacés par les composants de tab intégrés de Starlight

Phase 4 : Remappage de la Config de Barre Latérale

Les configs de barre latérale Docusaurus utilisant les schémas category/items sont converties au format de configuration de barre latérale de Starlight. Lorsque c'est possible, nous passons à des barres latérales générées automatiquement pilotées par la structure de fichiers, réduisant la maintenance de config à zéro.

// Docusaurus sidebars.js
module.exports = {
  docs: [
    { type: 'category', label: 'Getting Started', items: ['intro', 'installation'] },
  ],
};

// Starlight astro.config.mjs
starlight({
  sidebar: [
    { label: 'Getting Started', autogenerate: { directory: 'getting-started' } },
  ],
})

Phase 5 : Mappage des Plugins et Intégrations

Nous remplaçons les plugins Docusaurus par des intégrations Astro :

• @docusaurus/plugin-google-gtag → @astrojs/partytown d'Astro avec gtag inline
• @docusaurus/plugin-sitemap → @astrojs/sitemap
• Algolia DocSearch → Pagefind (intégré) ou plugin starlight-docsearch
• @docusaurus/plugin-client-redirects → Redirects Astro en config ou astro-redirect
• Plugins remark/rehype personnalisés → Transfert direct, même écosystème de plugins

Phase 6 : Migration de la Recherche

Si vous êtes sur Algolia DocSearch, nous migrons vers Pagefind par défaut. Pagefind indexe au moment du build, ne nécessite aucun service externe et offre une recherche instantanée avec correspondance floue. Si votre équipe a spécifiquement besoin d'Algolia — pour les analyses ou les réponses alimentées par l'IA — nous configurons le plugin officiel starlight-algolia à la place.

Phase 7 : QA et Lancement

Nous exécutons une comparaison de crawl complète entre les anciens et nouveaux sites, vérifions que chaque URL se résout, testons la fonctionnalité de recherche, validons le rendu mobile et confirmez que les scores Lighthouse atteignent nos objectifs.

Stratégie de Préservation SEO

Les sites de documentation accumulent une autorité de recherche significative. Nous protégeons chaque élément :

• Parité d'URL : Nous correspondons exactement à votre structure d'URL existante. Si Docusaurus servait /docs/getting-started, Starlight sert le même chemin
• Redirects 301 : Pour toute URL qui doit changer, nous configurons des redirects au niveau du serveur sur Vercel ou Cloudflare
• Tags canoniques : Chaque page obtient une URL canonique appropriée
• Génération de sitemap : @astrojs/sitemap produit un sitemap mis à jour soumis à Search Console
• Préservation des métas : Les tags de titre, les méta-descriptions et les tags Open Graph se transfèrent du frontmatter existant
• Données structurées : Nous ajoutons du JSON-LD spécifique à la documentation le cas échéant

Calendrier et Tarification

La plupart des migrations Docusaurus vers Starlight se complètent en 1-3 semaines selon la complexité du site :

• Petits sites (moins de 50 pages, composants personnalisés minimaux) : 1 semaine, à partir de 3 000 $
• Sites moyens (50-200 pages, composants personnalisés, versioning) : 2 semaines, à partir de 6 000 $
• Grands sites (200+ pages, personnalisation importante, locales multiples) : 3+ semaines, à partir de 10 000 $

Chaque projet commence par un audit de migration gratuit où nous évaluons votre configuration Docusaurus spécifique et fournissons une portée exacte et un calendrier.