Règles d'écriture des éléments de contenu : quand utiliser chaque bloc

Chaque page du playbook SEO repose sur une distinction : un contenu a un objectif, tandis que son niveau de titre et son apparence visuelle ne sont que de la présentation. Ces règles d’écriture des éléments transforment cette distinction en un contrat de production. Suivez-les avant d’appliquer un composant, de convertir un article entre systèmes de publication ou de modifier un élément qui apparaît déjà sur des pages publiées.

Aperçu rapide

• Consultez la bibliothèque d’éléments par objectif avant le nom. Si l’objectif d’un élément correspond à la tâche qu’une section accomplit, cet élément est obligatoire.
• Utilisez du Markdown simple uniquement après avoir confirmé qu’aucun élément typé ne représente l’objectif du passage. Le texte libre est un recours, pas une valeur par défaut.
• Rédigez d’abord l’article complet en texte brut. Appliquez les éléments lors d’un passage structurel séparé de haut en bas, afin que la composition et le balisage ne soient pas en concurrence pour attirer l’attention.
• Considérez la directive Markdown comme le contenu canonique rédigé. Les moteurs de rendu Hugo et WordPress transforment les mêmes champs et le même corps en sortie native de la plateforme.
• Maintenez les pages publiées existantes sur le sens sous lequel elles ont été relues. Un changement de définition cassant crée une nouvelle version et une migration explicite ; il ne réinterprète jamais silencieusement l’ancien contenu.

La règle de priorité directrice

La bibliothèque doit être consultée selon ce que fait un passage, et non selon ce que le rédacteur a choisi de l’appeler. Les noms varient : un rédacteur peut intituler une section « Qu’est-ce que le churn ? », un autre « Le churn expliqué », et un troisième « Une définition opérationnelle ». Leur objectif est identique, donc les trois correspondent au même élément de définition.

Cette priorité existe parce que le texte libre et un élément typé peuvent avoir la même apparence à l’écran tout en se comportant complètement différemment en aval. Un titre stylisé suivi d’un paragraphe peut ressembler à une boîte de définition dans le navigateur, mais il ne porte aucune identité de composant. Il ne peut pas produire de manière fiable la sortie structurée de la définition, exposer ses champs à un autre moteur de rendu, conserver sa sémantique lors d’une migration, ou être trouvé par un contrôle qualité qui vérifie si la page contient une définition. L’élément typé correspond à un composant et à une forme de données connue ; le texte libre visuellement similaire ne correspond à rien.

La règle est donc stricte :

Avant de rédiger ou d’approuver un titre ou un bloc de contenu, identifiez son objectif. Si cet objectif correspond à une définition d’élément, utilisez l’élément. La similarité visuelle, un H2 existant ou la capacité d’exprimer les mêmes mots dans un paragraphe ne rendent pas le texte libre équivalent.

La priorité est sémantique plutôt que visuelle. Une page peut toujours contenir des titres ordinaires à l’intérieur ou autour d’un élément lorsque sa définition le permet, mais le titre ne remplace jamais le type d’élément.

Texte libre versus élément typé

Utilisez ce chemin de décision jusqu’à ce que le diagramme partagé soit disponible :

1. Exprimez la fonction du passage en un seul verbe. Exemples : définir, avertir, résumer, comparer, prouver, instruire ou inviter à l’action. Cela empêche le texte du titre de masquer l’objectif sous-jacent.
2. Recherchez dans la bibliothèque par cet objectif et ses synonymes. Un rédacteur qui cherche uniquement le titre littéral « Qu’est-ce que X ? » peut passer à côté d’un élément de définition dont la page s’intitule « Boîte de définition ».
3. Utilisez l’élément correspondant lorsqu’il existe. Ne comparez pas les apparences et ne vous demandez pas si Markdown pourrait imiter le design ; le comportement enregistré est le facteur déterminant.
4. Utilisez le texte libre lorsqu’aucun objectif ne correspond. C’est correct pour les explications de liaison, les arguments, les analyses, le contexte narratif et les transitions qui appartiennent au flux principal de l’article et ne nécessitent aucun comportement de composant distinct.
5. Signalez un manque récurrent. Si le même objectif non couvert apparaît sur plusieurs pages, proposez un élément de bibliothèque au lieu d’inventer une directive ponctuelle ou un traitement CSS dans un article.

Le Markdown simple est véritablement correct lorsque les mots forment le raisonnement continu de l’article et n’ont pas besoin d’une étiquette indépendante, d’un contrat de données, d’une interaction ou d’un chemin de réutilisation. Par exemple, deux paragraphes expliquant pourquoi une recommandation découle des preuves précédentes sont une prose normale. Un ensemble compact de conclusions en haut n’est pas une prose normale simplement parce qu’il peut être rédigé sous forme de puces ; il a l’objectif reconnu d’un élément d’aperçu ou de points essentiels.

Confusions courantes qui entraînent un balisage incorrect

Ces cas sont listés explicitement car ils passent facilement une inspection visuelle. L’erreur ne devient visible que lorsqu’un autre moteur de rendu, validateur, index de recherche ou consommateur de sortie structurée reçoit la page.

La distinction entre les points essentiels et un aperçu rapide est particulièrement importante. Utilisez les points essentiels lorsque les éléments sont des conclusions que le lecteur doit retenir, ce qui signifie qu’ils peuvent souvent être rédigés seulement après que l’article existe. Utilisez un aperçu lorsque les éléments orientent le lecteur sur la portée ou la séquence avant la lecture. Choisissez selon cette fonction éditoriale, même si le thème actuel donne aux deux composants une apparence similaire.

Syntaxe des directives et attributs

La forme Markdown canonique utilise une directive de bloc nommée. Les attributs suivent le nom de la directive entre accolades :

:::nom-élément{clé=valeur clé2="valeur avec espaces" .classe}
Contenu du corps
:::

Les attributs existent pour porter des propriétés petites et stables qui affectent le sens de l’élément ou sa présentation prise en charge. Les garder lisibles par machine empêche les rédacteurs de cacher la configuration dans la prose. Utilisez clé=valeur pour une valeur sans espaces et clé2="valeur avec espaces" lorsque des espaces sont présents. Une valeur d’attribut non citée ne peut pas contenir d’espaces. Un point en tête ajoute une classe prise en charge, comme dans .compact ; ce n’est pas un endroit pour inventer un style spécifique à une page.

Les clés d’attribut sont en minuscules et utilisent l’orthographe exacte définie sur la page de l’élément. Les valeurs booléennes et énumérées suivent également le contrat de cette page. Ne créez pas d’attribut parce qu’un moteur de rendu le tolère par hasard : un attribut non déclaré n’a aucune garantie multiplateforme.

Les délimiteurs de fermeture ::: appartiennent à l’élément externe. Gardez-les sur leurs propres lignes afin qu’un analyseur puisse distinguer le corps du paragraphe suivant. Les exemples de code qui montrent des directives doivent rester à l’intérieur de blocs de code délimités, comme ils le font sur cette page, afin que Hugo ne les interprète pas comme du contenu.

Mappage du corps par défaut

La plupart des éléments ont besoin d’un titre court et d’un corps plus long. Exiger des auteurs qu’ils répètent ces éléments comme attributs rendrait les longs textes difficiles à éditer et faciles à échapper incorrectement, donc le corps fournit le mappage par défaut :

:::exemple
## Un titre concret

Le reste du corps peut contenir des paragraphes, listes, liens et autres contenus autorisés par la définition de l'élément.
:::

Sauf si une page d’élément remplace explicitement la règle, le premier titre dans le corps correspond à title, et tout ce qui suit ce titre correspond à content. Le marqueur de titre exprime la hiérarchie source pour les éditeurs ; le champ mappé permet à chaque plateforme de rendre le niveau de titre sémantique approprié dans son contexte.

Seul le premier titre du corps bénéficie de ce traitement spécial. Les titres suivants restent partie de content. Si le corps n’a pas de titre, title est absent ; cela n’est valide que lorsque la définition de l’élément marque son titre comme optionnel. Si un élément définit des emplacements nommés ou un mappage différent, sa propre page prévaut sur cette valeur par défaut car le moteur de rendu doit savoir exactement où appartient chaque fragment.

Éléments imbriqués

Certains éléments contiennent une liste répétable dont chaque entrée a besoin d’attributs et d’un corps, comme des étapes avec identifiants, des cartes avec étiquettes ou des éléments de liste de vérification avec un état initial. Aplatir ces entrées en une seule liste Markdown ferait perdre leurs champs individuels, donc les éléments imbriqués utilisent une directive d’élément explicite :

:::élément-parent{variante=compact}
::élément{clé=valeur}
### Titre du premier élément

L'explication du premier élément.
::
::élément{clé2="valeur avec espaces"}
### Titre du deuxième élément

L'explication du deuxième élément.
::
:::

Le contrat est ::élément{clé=valeur} … :: : deux points ouvrent chaque élément, le nom singulier est élément, et deux points le ferment. Le parent conserve son délimiteur de fermeture à trois points. Cette différence visuelle est importante car elle rend l’imbrication non ambiguë sans recourir à l’indentation, qui est facilement endommagée par le copier-coller.

Chaque élément applique le même mappage de corps par défaut, sauf si la page de l’élément parent dit le contraire : son premier titre devient le title de cet élément, et le reste devient son content. Placez les attributs sur l’élément lorsqu’ils décrivent uniquement cet élément ; placez-les sur le parent lorsqu’ils affectent l’ensemble de la collection.

Liens, images et boutons en ligne

Une source portable nécessite des chemins prévisibles. Une URL relative doit être relative à la racine du site, et non au fichier Markdown actuel, car la même source peut être rendue à une profondeur de système de fichiers différente dans Hugo ou importée dans WordPress.

• Les liens vers des pages internes utilisent une barre oblique au début et à la fin, comme le lien bibliothèque d’éléments . N’utilisez pas ../, n’omettez pas la barre oblique initiale, et ne codez pas en dur le domaine de production pour une page interne.
• Les liens externes utilisent une URL https:// complète. Le schéma fait partie de la destination et ne doit pas être déduit par un moteur de rendu.
• Les fichiers sources d’images se trouvent sous cdn-assets/seo-playbook/, et leurs chemins publics commencent par /cdn-assets/seo-playbook/. Ajoutez le groupe et le nom de fichier approuvés seulement après que l’actif existe.
• Le texte alternatif décrit l’information véhiculée par une image, pas son nom de fichier ou son apparence décorative. Une image décorative utilise un texte alternatif vide, mais la page d’élément concernée doit explicitement autoriser la décoration.
• Un appel à l’action en ligne utilise :button[Étiquette visible]{href="/cible/"}. Le texte entre crochets est l’étiquette accessible et href suit les mêmes règles de chemin interne ou externe. Utilisez un bouton uniquement pour une véritable action suivante, pas pour rendre un lien de référence ordinaire plus visible.

Une image est un contenu, pas une solution de contournement pour une mise en page non prise en charge. Si l’image contient des étiquettes, des chiffres ou des instructions essentiels, répétez cette information dans un texte accessible ou utilisez un élément structuré qui l’expose. Les demandes de capture d’écran restent des commentaires HTML jusqu’à ce que l’actif nommé existe ; ce ne sont pas des références d’image publiées et doivent définir screenshotsPending = true dans le frontmatter.

Les éléments de frontmatter et de corps ont des fonctions différentes

Le frontmatter décrit le document en tant que document. Les directives du corps décrivent des blocs significatifs à l’intérieur de l’expérience de lecture. Garder ces couches séparées permet aux pages de listage, schémas, routage et outils de publication de lire les métadonnées sans analyser la prose visible.

Les éléments de métadonnées vivent donc dans le frontmatter : titre de page, description, mots-clés, dates de publication et de mise à jour, informations canoniques ou d’alias, propriété, taxonomie, jointures de playbook et toutes les collections orientées schéma que le contrat de page y place, comme les entrées FAQ sur les pages academy. Ces champs ne sont jamais écrits comme des directives :::. Un bloc visible qui répète certaines métadonnées ne déplace pas le champ faisant autorité hors du frontmatter ; il reçoit son propre élément de corps uniquement lorsqu’il a un objectif distinct orienté lecteur.

Les éléments de contenu vivent dans le corps : définitions, avertissements, astuces, aperçus, points essentiels, listes de vérification, comparaisons, blocs de preuve, exemples, étapes et appels à l’action. Ce sont des directives car leur emplacement dans le récit est important. Déplacer un avertissement dans le frontmatter le déconnecterait du passage qu’il qualifie ; cacher des métadonnées dans une directive de corps empêcherait les systèmes au niveau du document de les trouver de manière fiable.

Les métadonnées sont obligatoires par défaut

Les métadonnées pilotent les chemins, aperçus, découvertes, jointures et sorties structurées avant que quiconque lise le corps. Un champ omis peut donc casser des consommateurs qui ne rendent jamais l’article. Pour cette raison, chaque élément de métadonnée est obligatoire sauf si sa page d’élément précise explicitement qu’il est optionnel.

Obligatoire signifie renseigné avec une valeur valide, pas simplement présent comme une chaîne vide ou une collection vide. Ne déduisez pas le caractère optionnel de l’omission d’une autre page, et n’ajoutez pas de valeurs factices pour satisfaire la validation. Si une valeur obligatoire n’est pas encore connue, la page n’est pas prête à être publiée. Les éléments de corps suivent les règles d’exigence des types de publication et des pages d’élément concernés plutôt que cette valeur par défaut des métadonnées.

Écrivez d’abord, appliquez les éléments ensuite

La sélection des éléments est une tâche de classification, tandis que la rédaction est une tâche de raisonnement. Essayer d’effectuer les deux phrase par phrase amène le rédacteur à optimiser prématurément pour les limites des composants. Le résultat habituel est des transitions plus faibles, des explications superficielles calibrées pour une boîte, des titres répétitifs créés pour satisfaire le balisage, et des directives choisies parce qu’elles sont pratiques plutôt que parce que leur objectif correspond.

La production se déroule donc en deux passages distincts :

1. Rédigez l’article entier en texte brut. Complétez l’argumentation, les exemples, les nuances, les transitions et la conclusion. À ce stade, les titres peuvent décrire la logique du brouillon, mais ils ne fixent pas le type d’élément final.
2. Appliquez les éléments lors d’un passage structurel séparé de haut en bas. Pour chaque titre et bloc, énoncez son objectif, consultez la bibliothèque, encadrez les sections correspondantes, ajoutez les attributs déclarés, et confirmez le mappage du corps et l’imbrication.

La séparation améliore les deux résultats. La prose se développe selon les questions du lecteur plutôt que selon les tailles de boîtes du thème actuel, tandis que le passage de balisage peut comparer des blocs similaires de manière cohérente dans tout le document. Elle rend également les omissions visibles : un rédacteur peut voir que l’article contient un avertissement ou une définition avant de décider comment l’encoder.

Après le passage structurel, lisez la page une fois sans regarder les noms de directives. Les éléments doivent soutenir un article cohérent, pas le transformer en un empilement de widgets déconnectés. Ensuite, inspectez la source une fois sans juger la prose, en vérifiant les délimiteurs, les attributs, les éléments imbriqués, les chemins et les métadonnées requises.

Le contrat des trois notations

Un élément est défini une fois par son objectif, ses champs canoniques, ses valeurs autorisées, son mappage de corps, son comportement d’accessibilité, son comportement de sortie structurée et sa version. Cette définition est la source de vérité. Les trois notations de plateforme sont des adaptateurs vers elle, pas trois conceptions de composants indépendantes.

Les formes représentatives expliquent le mappage ; la page individuelle de l’élément publie son nom et ses champs exacts pris en charge. Les auteurs travaillent dans la notation requise par leur flux de travail de publication, mais ils ne renomment pas les champs, n’ajoutent pas de significations propres à une plateforme, et n’imitent pas manuellement le HTML d’un autre moteur de rendu.

Le propriétaire de l’élément maintient la définition canonique et décide si un changement proposé est compatible ou versionné. Les mainteneurs Hugo et WordPress possèdent leurs adaptateurs et les testent contre des fixtures partagées : le même titre, contenu, attributs, éléments, liens et attentes d’accessibilité doivent survivre aux trois chemins. Les propriétaires éditoriaux vérifient l’objectif et les exemples. Aucun mainteneur de plateforme ne peut redéfinir la signification éditoriale localement ; si une plateforme ne peut pas exprimer le contrat, c’est un défaut d’adaptateur ou une proposition de modification du contrat.

Ce modèle permet à la présentation de différer là où les plateformes l’exigent tout en maintenant la sémantique stable. Hugo peut rendre du HTML côté serveur et WordPress peut stocker un commentaire de bloc, mais un avertissement reste un avertissement, un élément de liste de vérification reste un élément, et les mêmes champs requis restent disponibles en aval.

Versionnement des éléments publiés

Le contenu publié a été relu selon la signification de l’élément qui existait au moment de la publication. Modifier silencieusement cette signification peut altérer les avertissements, les données structurées, l’accessibilité ou les importations sans qu’un éditeur touche à la page. Le versionnement protège cette approbation éditoriale.

Utilisez la politique de changement suivante :

• Changement de rendu compatible : Un raffinement visuel, une amélioration de performance ou une correction de bug qui préserve l’objectif, les champs, les valeurs acceptées, le mappage du corps et la signification de sortie peut être livré dans la version actuelle. Les pages existantes le reçoivent via le moteur de rendu.
• Changement additif compatible : Un nouvel attribut optionnel peut rejoindre la version actuelle uniquement lorsque son absence préserve la sortie existante et que chaque adaptateur peut l’ignorer ou le supporter en toute sécurité. La définition et les tests de plateforme changent ensemble.
• Changement cassant : Un champ renommé ou supprimé, un nouveau champ obligatoire, un mappage de corps modifié, un objectif modifié, une valeur par défaut modifiée avec effet sémantique, ou une structure d’élément imbriqué incompatible crée une nouvelle version majeure de l’élément.
• Dépréciation : L’ancienne version reste rendable pour les pages publiées. Sa page d’élément identifie le remplacement et le chemin de migration ; les nouvelles pages utilisent la version actuelle.
• Migration : Une migration de contenu est explicite, cadrée, prévisualisée sur Markdown, Hugo et WordPress, et validée éditorialement avant publication. Enregistrez quelles pages ont changé et pourquoi. Ne faites pas deviner à un moteur de rendu comment l’ancienne source devrait être réinterprétée.

Lorsqu’aucune version n’est écrite dans la source, l’élément utilise la version de base définie lors de l’adoption de ce contrat. Cette ligne de base implicite doit rester stable. Les nouvelles versions majeures s’identifient via le mécanisme de version déclaré sur la page de l’élément ; elles ne réaffectent pas la syntaxe non versionnée.

Le retour en arrière est également important. Conservez l’ancien moteur de rendu et la représentation source disponibles jusqu’à ce que les pages migrées passent les vérifications structurelles, visuelles, d’accessibilité et de sortie structurée. Si une migration échoue, restaurez le mappage de la version précédente plutôt que d’aplatir l’élément en texte libre, ce qui supprimerait la sémantique que le versionnement est censé protéger.

Liste de vérification pour la révision de production

Utilisez cette révision finale après le passage de prose et le passage d’éléments :

• L’objectif de chaque bloc non-prose peut-il être énoncé en un seul verbe ?
• La bibliothèque a-t-elle été consultée par cet objectif et des synonymes proches ?
• Chaque objectif correspondant utilise-t-il son élément typé, même lorsqu’un H2 et un paragraphe auraient une apparence similaire ?
• Chaque passage restant en texte libre fait-il partie de l’explication, de l’analyse, du récit ou de la transition continue de l’article ?
• Les attributs suivent-ils le format {clé=valeur clé2="valeur avec espaces" .classe}, avec les espaces entre guillemets et seulement les clés déclarées utilisées ?
• Le premier titre du corps correspond-il à title et le reste à content, sauf si la page de l’élément déclare un autre mappage ?
• Les enfants répétables utilisent-ils ::élément{clé=valeur} … ::, avec les attributs du parent et de l’élément placés au niveau correct ?
• Les liens internes sont-ils relatifs à la racine avec des barres obliques au début et à la fin, les liens externes absolus, et les chemins d’images à l’intérieur de la racine d’images approuvée ?
• Les champs de métadonnées sont-ils dans le frontmatter, jamais dans des directives du corps, et toutes les valeurs de métadonnées requises sont-elles complètes ?
• Les mêmes champs canoniques peuvent-ils être mappés sans perte vers Markdown, Hugo et WordPress ?
• Tout changement de définition préserve-t-il les anciennes pages ou introduit-il une version explicite et une migration ?

Cette page est un prérequis pour chaque page d’élément individuelle. Chaque définition d’élément doit renvoyer à ces règles de base, puis documenter uniquement ses exceptions spécifiques à l’objectif : attributs pris en charge, champs requis, remplacements de mappage du corps ou d’élément, imbrication autorisée, noms de plateforme exacts et historique des versions. Si une page d’élément est silencieuse, les valeurs par défaut de cette page s’appliquent.