La migration de plateformes de documentation massives, telles que MDN Web Docs, représente un défi technique majeur en raison du volume de fichiers, de l'entrelacement des liens et de la nécessité de préserver l'historique des données. Le dépôt mdn/content sert de socle à cette nouvelle architecture. Ce guide détaille les processus de transition pour assurer une migration fluide tout en évitant les régressions structurelles.
Analyse de l'organisation du dépôt
L'architecture du contenu repose sur une arborescence rigoureuse. La majorité des documents se situe dans le répertoire files/en-us/. Ce dernier est segmenté par domaines technologiques :
- web/ : Regroupe les spécifications fondamentales comme le HTML, le CSS et le JavaScript.
- glossary/ : Contient les définitions des termes techniques.
Chaque unité de contenu est encapsulée dans un fichier index.md situé dans son propre dossier thématique. Par exemple, la documentation sur les tableaux en JavaScript se trouve sous files/en-us/web/javascript/reference/global_objects/array/index.md. Cette organisation granulaire nécessite une gestion précise lors des déplacements de répertoires.
Configuration de l'environnement de travail
Avant d'initier toute modification, il est impératif de configurer l'environnement local. Le projet s'appuie sur Node.js et l'outil de gestion de paquets Yarn.
# Récupération du dépôt source
git clone https://github.com/mdn/content.git source-mdn
cd source-mdn
# Initialisation des dépendances
yarn install
# Lancement de l'instance de prévisualisation
yarn run start
Une fois le serveur démarré, le contenu est accessible localement via http://localhost:5042/, permettant de valider les rendus en temps réel durant la migration.
Manipulation du contenu et gestion des redirections
Pour modifier l'emplacement d'un document sans rompre l'expérience uitlisateur, l'outil CLI intégré est privilégié. La commande move automatise le déplacement physique des fichiers et la création des règles de redirection.
# Syntaxe : yarn content move <ancien-slug> <nouveau-slug>
yarn content move web/css/properties/flex-direction web/css/flexbox/direction
Cette opération met à jour automatiquement le fichier files/en-us/_redirects.txt. Il est fortement déconseillé de modifier ce fichier manuellement, car une erreur de syntaxe pourrait briser la navigation globale du site. Pour ajouter une redirection simple sans déplacer de fichier, on utilisera yarn content add-redirect.
Mise à jour automatisée des références internes
Le déplacement d'un fichier invalide les liens pointant vers lui depuis d'autres documents Markdown. Pour résoudre ce problème à grande échelle, un script de maintenance est disponible.
# Analyse et correction automatique des liens brisés
node scripts/update-moved-file-links.js
# Mode vérification uniquement (sans modification)
node scripts/update-moved-file-links.js --check
Le script parcourt l'intégralité du corpus Markdown et HTML pour détecter les chemins obsolètes et les remplacer par les nouveaux slugs définis dans le système de redirection.
Protocoles de validation post-migration
Une migration n'est considérée comme achevée qu'après une phase de validation rigoureuse :
- Vérification de l'intégrité : Comparer le nombre de fichiers déplacés et s'assurer qu'aucun bloc de métadonnées (front-matter) n'a été altéré.
- Test de navigation : Vérifier que les anciennes URLs pointent correctement vers les nouvelles via les en-têtes HTTP de redirection.
- Rendu visuel : Utiliser le serveur local pour confirmer que les macros et les exemples de code interactifs sont toujours fonctionnels dans le nouveau contexte structurel.
Bonnes pratiques pour les contributeurs
La maintenance d'un tel volume de données exige le respect de normes strictes. Chaque modification doit faire l'objet d'une Pull Request documentée. L'utilisation systématique des outils CLI garantit la cohérence entre la structure des fichiers et la base de données des redirections, assurant ainsi la pérennité de l'accès à l'information pour les développeurs web du monde entier.