Architecture
L’architecture du site définit comment le matériel source devient une page publiée. Le site utilise trois patrons principaux : des pages Markdown écrites à la main, des pages Markdown qui rendent des données structurées, et des pages générées au moment de la compilation par des adaptateurs de contenu Hugo.
Les pages d’architecture expliquent la mécanique d’implémentation. Les pages de gouvernance décident de la responsabilité, du nommage, des règles de contenu et de la stratégie.
Emplacement canonique#
L’emplacement canonique est l’endroit durable où une information est maintenue. D’autres pages peuvent la résumer, la lister, la traduire ou pointer vers elle, mais un seul endroit est traité comme la source de vérité.
| Matériel | Emplacement canonique |
|---|---|
| Essais et notes longues | Billets de blogue |
| Petites choses apprises | Entrées AJA |
| Conférences, publications et références répétables | Fichiers de données plus une page de rendu |
| Nombreux enregistrements qui ont besoin de pages | Fichiers de données plus un adaptateur de contenu |
| Travaux publiés d’abord ailleurs | Pages d’archives locales pointant vers les sources |
Le test pratique est simple : si cette information doit être mise à jour dans six mois, où le changement devrait-il se faire?
Guide des patrons#
Utilisez le plus petit patron qui préserve la responsabilité et rend les prochains changements évidents.
| Patron | À utiliser quand | Détails |
|---|---|---|
| Page Markdown | La page elle-même est l’artefact | Gouvernée par les règles de contenu et de front matter |
| Page pilotée par les données | Une page durable présente des faits structurés | Pages pilotées par les données |
| Adaptateur de contenu | Plusieurs enregistrements doivent devenir des pages Hugo normales | Adaptateurs de contenu |
| Front matter | Les métadonnées de page, les profils de composants et les archétypes de dossiers orientent le rendu | Front matter |
| Migration des composants | Un audit généré et un déploiement répétable standardisent la documentation des composants | Migration des composants |
| Archétypes | Des fichiers de départ réutilisables créent des formes de contenu connues | Archétypes |
| Chaîne d’assets | Le CSS, la sortie des jetons, le JavaScript, les polices et les empreintes sont regroupés | Chaîne d’assets Hugo |
| Architecture des jetons | La source DTCG, les collections de thèmes, les artefacts générés et les vérifications restent alignés | Architecture des jetons |
| Mécanique i18n | Des chaînes d’interface, des alternatives de langue et des gabarits sensibles à la langue sont en jeu | i18n |
| Surface générée | Une source de données rend une référence précise, comme le glossaire de marque | Génération du glossaire |
| Diagramme Mermaid | Des diagrammes en texte structuré documentent l’architecture, les flux et les relations | Syntaxe des diagrammes Mermaid |
Préférez les fichiers Markdown explicites pour les pages éditoriales durables. Préférez les données structurées lorsque les faits se répètent. Utilisez les adaptateurs de contenu seulement lorsque des enregistrements de données ont besoin de leurs propres URL, métadonnées, comportements de recherche, alternatives de langue ou comportements de taxonomie.
| Adaptateurs de contenu | Comment les adaptateurs de contenu Hugo transforment des enregistrements de données en pages générées | |
| Archétypes | Fichiers de départ Hugo réutilisables pour les formes de contenu récurrentes | |
| Architecture des jetons | Comment les jetons DTCG, les collections de thèmes, les artefacts générés et les consommateurs restent alignés | |
| Bibliothèque de motifs | Le modèle de données et la recette d’implémentation pour les compositions documentées de composants | |
| Chaîne d’assets Hugo | Comment Hugo regroupe le CSS généré des jetons, le CSS du site, le JavaScript et les polices | |
| Front matter | Comment les métadonnées de page, les profils de composants et de motifs, et les archétypes de dossiers orientent la documentation rendue | |
| Génération du glossaire | Comment les données du glossaire sont rendues dans la documentation de marque | |
| i18n | Comment les chaînes d’interface sont traduites : où vivent les clés, comment les gabarits les appellent et ce qui arrive quand l’une manque | |
| Migration des composants | La recette de déploiement et l’audit vivant de la documentation standardisée des composants | |
| Pages pilotées par les données | Comment les données structurées sont rendues dans des pages de référence durables | |
| Shortcodes | Comment les shortcodes font le lien entre la rédaction Markdown et la logique de mise en page Hugo réutilisable | |
| Syntaxe des diagrammes Mermaid | Familles de diagrammes Mermaid prises en charge et moments où les utiliser dans la documentation |