Rédiger des pages de documentation MDX qui suivent les règles du site et se compilent sans erreur

## Comprendre l’organisation du site de documentation avant d’écrire Considérez le dépôt comme une application de documentation pilotée par des schémas, et non comme une collection disparate de fichiers Markdown. Identifiez le générateur du site, le thème de documentation, le framework de composants, le gestionnaire de paquets, la version de l’environnement d’exécution et la cible de déploiement. Installez les dépendances avec la commande verrouillée et reproductible du dépôt. Maintenez les versions de l’environnement d’exécution et du gestionnaire de paquets alignées sur les métadonnées du dépôt. Vérifiez la branche principale de contribution au lieu de supposer un nom conventionnel. Différenciez les pages destinées aux utilisateurs, les partiels réutilisables, les journaux des modifications, les données du glossaire, les métadonnées des produits et les autres collections structurées. Maintenez les composants personnalisés, les schémas de contenu, les extensions Markdown, les extensions de coloration du code, les icônes, les ressources, les styles et les routes dynamiques dans leurs couches désignées. Traitez les fichiers publics statiques différemment des images traitées par le générateur du site. Utilisez le module central d’exportation des composants comme interface publique d’importation pour MDX. Considérez les schémas des collections comme l’autorité pour les champs et les types de valeurs acceptés. Traitez les répertoires générés de compétences ou de références comme des produits de la compilation. Ne modifiez pas les répertoires générés et n’intégrez pas dans un commit le contenu généré ignoré. Lisez les instructions imbriquées avant de modifier un robot de revue spécialisé ou un worker de déploiement. Utilisez les références de style, de composants et de procédures propres au dépôt comme consignes faisant autorité. Ne laissez pas les habitudes générales de Markdown prévaloir sur les règles MDX et les schémas du site. ## Ranger les pages dans les bons dossiers et bien nommer les fichiers Placez les pages de documentation destinées aux utilisateurs sous le répertoire du produit ou du sujet. Placez les extraits réutilisables dans la collection des partiels. Placez les entrées du journal des modifications dans le sous-répertoire correspondant au produit ou au sujet. Placez les termes du glossaire et les autres métadonnées structurées dans les collections régies par leurs schémas. Exigez une page d’index dans chaque dossier de contenu navigable lorsque le site en attend une. Utilisez des noms de fichiers en minuscules dont les mots sont séparés par des tirets. Limitez les répertoires de contenu aux extensions de texte et de données explicitement autorisées. Les types généralement autorisés sont MDX, JSON, YAML et le texte brut. Laissez la validation des extensions appliquer la liste d’autorisation au lieu de dissimuler les fichiers non pris en charge. Ne placez pas d’images ni de fichiers binaires arbitraires dans les répertoires de contenu analysés par les schémas. Placez les images pouvant être traitées dans l’arborescence de ressources dédiée à l’optimisation. Ne placez les fichiers réellement statiques dans l’arborescence publique que lorsqu’ils doivent être servis sans modification. Maintenez les noms des répertoires alignés sur les métadonnées de produits existantes. Ne créez pas de journal des modifications ni de sous-répertoire de collection pour une clé de produit inconnue. Préservez les limites établies des collections au lieu d’inventer un emplacement de contenu parallèle. Lorsque vous déplacez une page, mettez à jour les liens entrants, les métadonnées de navigation, les redirections et les références aux partiels associés. ## Remplir les données de page (frontmatter) exigées par le site Fournissez à chaque page de documentation un bloc de frontmatter conforme au schéma de sa collection. Fournissez un titre de page concis. Fournissez une description de recherche chaque fois que le type de contenu sélectionné l’exige. Choisissez le type de page dans l’énumération autorisée du dépôt. Les types courants comprennent `concept`, `configuration`, `example`, `FAQ`, `getting started`, `how-to`, `integration`, `implementation`, `overview`, `reference`, `release notes`, `solution`, `troubleshooting` et `tutorial`. Utilisez des types spécialisés comme `design guide`, `learning unit`, `navigation`, `reference architecture` et `video` lorsque le schéma les fournit. N’utilisez l’ordre de la barre latérale que lorsqu’un classement explicite est nécessaire. N’utilisez un libellé de barre latérale que lorsque le texte de navigation doit différer du titre de la page. Référencez les produits ou les sujets à l’aide des clés de métadonnées existantes. Utilisez l’énumération de difficulté documentée pour le contenu des tutoriels. Consignez les dates de revue au format obligatoire année-mois-jour. N’inventez pas de champs de schéma ni de valeurs d’énumération. Maintenez valides l’indentation YAML et la structure des listes. Régénérez les types des collections de contenu après avoir modifié les définitions de collections ou les schémas. Validez les fichiers de données par rapport à leur schéma plutôt que de vous fier à une inspection visuelle. Maintenez les métadonnées de la page synchronisées lorsque sa finalité, son produit, son titre ou son état de revue change. ## Rédiger des pages MDX qui se compilent sans erreur de syntaxe Suivez le guide de rédaction et de formatage faisant autorité dans le dépôt. Considérez MDX comme du Markdown complété par un langage de composants intégré dont l’analyse est plus stricte. Échappez les accolades et les chevrons, ou appliquez-leur un format de code, lorsqu’ils font partie du texte. N’oubliez pas que MDX interprète ces caractères comme des expressions ou des composants, même dans le texte. Importez tous les composants utilisés par la page. Placez les importations immédiatement après le frontmatter et avant le contenu de la page. Utilisez uniquement les identifiants de langage pris en charge pour la coloration syntaxique. Rédigez la sortie générique du terminal avec l’identifiant de texte brut du dépôt. Utilisez des identifiants de langage en minuscules dans les blocs de code. Utilisez des chemins absolus depuis la racine pour les liens internes du site. N’utilisez pas d’URL complètes de production pour les destinations internes. N’utilisez pas de liens de pages relatifs qui ne sont pas pris en charge. Maintenez les niveaux de titres dans l’ordre et ne sautez aucun niveau. Omettez les symboles d’invite du shell dans les commandes qui peuvent être copiées. Rédigez des étapes concises dont l’action, l’emplacement et le résultat attendu sont sans ambiguïté. Conservez les explications réutilisables dans des partiels lorsque plusieurs pages ont besoin du même texte maintenu. Vérifiez les exemples de code par rapport à l’API documentée et au comportement actuel du produit. ## Utiliser les composants et images du site, et ne modifier les redirections qu’en cas de besoin Importez les composants MDX uniquement par l’intermédiaire du module central d’exportation des composants du dépôt. Consultez la documentation des composants pour connaître les propriétés obligatoires et les contraintes d’utilisation. Ne copiez pas les éléments internes d’un composant dans le contenu lorsqu’un composant public pris en charge existe. Placez le code des nouveaux composants dans le répertoire de composants désigné. Utilisez le préfixe obligatoire des éléments personnalisés et la convention de nommage kebab-case. Conservez chaque composant dans un répertoire portant le nom de ce composant. Utilisez des noms de classes en PascalCase avec le suffixe obligatoire. Ne renommez pas des éléments hérités exemptés uniquement pour appliquer une règle de préfixe plus récente. Conservez les images sources dans le répertoire de ressources optimisées de leur produit ou sujet. Vérifiez les chemins des images au moyen d’une compilation locale complète. Ne modifiez les redirections que lorsqu’un déplacement de page ou une migration d’URL l’exige. Terminez les chemins sources des redirections par la barre oblique obligatoire ou par un suffixe de fichier ou de caractère générique accepté. Ne placez pas de fragments dans les URL sources des redirections. Détectez les boucles de redirection avant la revue. Exécutez le validateur de redirections dédié chaque fois que le fichier de redirections change. Maintenez les modifications des composants, images, liens et redirections dans le périmètre prévu de la page. ## Passer les contrôles en local et en CI avant de dire qu’une page est prête Exécutez la vérification des schémas et des types après chaque modification de contenu. Utilisez une compilation locale complète pour valider l’analyse MDX, les chemins des images et les liens internes. Activez la vérification des liens internes pendant la compilation locale de validation complète. N’exécutez pas dans une intégration continue contrainte une compilation complète dont on sait qu’elle dépassera le délai imparti. Dans l’intégration continue, exécutez les vérifications de types, de lint et de formatage comme ensemble sûr réduit. Pour les modifications de code, exécutez également les suites de tests complètes du dépôt. Formatez chaque fichier modifié avant de l’inclure dans un commit. Exécutez la vérification du formatage du dépôt après les corrections automatiques. N’exécutez la validation des redirections que lorsque leur configuration a changé. Exécutez la synchronisation des types de collections après toute modification de schéma ou de collection. Alignez la séquence locale de validation complète sur le pipeline d’intégration continue lorsque c’est possible. Attendez-vous à ce que l’intégration continue vérifie les extensions de fichiers, les types, le lint, le formatage, la compilation et les liens, les redirections et les tests. Considérez les avertissements de l’analyseur de style comme des preuves pour la revue, même lorsqu’ils ne constituent pas des échecs bloquants. N’indiquez pas qu’une page est prête tant qu’une porte de validation directement pertinente manque. Distinguez une limite de l’environnement d’intégration continue d’une défaillance réelle du contenu. Réexécutez les vérifications directement affectées après chaque modification corrective. ## Donner à chaque entrée du répertoire un ID créé par l’outil du site et le garder Attribuez à chaque fichier de données d’entrée de répertoire un identifiant unique et stable à l’emplacement obligatoire de la première ligne. Utilisez la longueur exacte d’identifiant et le jeu de caractères réduisant les confusions du dépôt. Pour un schéma à six caractères, vérifiez que chaque valeur générée comporte exactement six caractères. Excluez les caractères visuellement ambigus lorsque le schéma l’exige. Générez les identifiants aléatoirement au lieu de les dériver des noms. Ne créez pas, ne devinez pas et ne copiez pas manuellement un identifiant. Utilisez l’outil d’identifiants du dépôt pour vérifier la collection complète. Utilisez son mode de correction pour les identifiants absents, mal formés ou dupliqués. Conservez un identifiant valide existant lorsque le nom affiché ou le nom du fichier change. Ne modifiez un identifiant existant que pour réparer une erreur de validation confirmée. Utilisez systématiquement l’unique extension YAML obligatoire. Considérez la génération d’identifiants comme une opération automatisée, et non comme un choix éditorial. Vérifiez l’unicité dans l’ensemble de la collection de répertoires. Conservez la génération d’identifiants et la validation des schémas dans l’intégration continue. Examinez le diff de l’outil avant d’intégrer les modifications générées dans un commit. N’ajustez pas manuellement un identifiant généré après la réussite de l’outil. ## Suivre les guides de chaque tâche et les règles de commit pour proposer des changements Utilisez le routeur de contributions du dépôt avant de rédiger, modifier, examiner des exemples, ajouter des journaux de modifications ou préparer une pull request. Suivez la référence propre à la tâche sélectionnée par ce routeur. Lisez les instructions locales d’un robot spécialiste avant de modifier son code, le routage de son flux de travail, son état ou son déploiement. Maintenez les liens symboliques propres aux outils dirigés vers la configuration partagée des agents enregistrée dans le dépôt. Ne chargez une compétence du dépôt que lorsque sa description correspond à la tâche. Utilisez le guide de style faisant autorité pour les décisions de rédaction et de formatage. Utilisez le catalogue de composants pour les propriétés, les exemples et les modèles obligatoires. Utilisez le guide de procédures pour les instructions étape par étape. Exécutez des tests dans chaque espace de travail d’exécution affecté par une modification de code. Maintenez distincts les tests du worker, de l’environnement d’exécution du serveur et du générateur du site. Rédigez les commits sous la forme acceptée par le dépôt, avec un préfixe de produit ou de type. Rendez les descriptions des commits propres à la correction visible par l’utilisateur ou à la correction technique. N’incluez pas de formatage, de contenu généré ni de modifications de produit sans rapport. N’approuvez que lorsque le contenu, les schémas, les importations, les ressources, les liens, les redirections, les tests et les conventions de contribution concordent.