Conventions de nommage

Les bons noms sont ennuyeux de la bonne façon. Ils se trient bien, survivent aux migrations et rendent l’utilité de chaque chose facile à reconnaître plus tard.

Utilisez la convention raisonnable la plus stricte lorsqu’un nom peut traverser plusieurs systèmes : macOS, Linux, Windows, Git, GitHub, SharePoint, OneDrive, Google Drive, archives, outils de synchronisation et URL. Le long article sur le nommage des fichiers sur BHDicaire.com porte le contexte de portabilité; cette page porte la règle du système de marque.

Règle générale#

Utilisez des noms qui décrivent le rôle et le propriétaire, pas la première page où la chose est apparue.

• Préférez les noms significatifs : footer, docs-shell, data-page/table-wrap
• Préférez les rôles stables aux noms de page : section-overview-table, pas home-overview-table, quand le motif n’est plus limité à la page d’accueil
• Utilisez le kebab-case en minuscules pour les fichiers, dossiers, slugs, classes CSS et la plupart des identifiants dans le contenu
• Évitez les noms qui ne diffèrent que par la casse
• Évitez les espaces, les emojis, les noms trop ponctués et les abréviations opaques
• Gardez les noms assez courts pour rester lisibles dans les chemins, les URL, les terminaux et les diffs

Noms de fichiers et de dossiers#

Utilisez ce jeu de caractères sûr pour les noms de fichiers et de dossiers portables :

a-z 0-9 - _ .

Préférez le kebab-case pour le contenu et les fichiers proches du code :

naming-conventions.en.md
url-strategy.fr.md
machine-readable.en.md

Utilisez les traits de soulignement seulement lorsqu’ils séparent des blocs de métadonnées, surtout dans les fichiers exportés ou archivés :

YYYYMMDD_scope_kind_subject_v##.ext
20260804_brand_docs-naming-conventions_v01.md

Gardez un budget pratique conservateur :

Contenu Hugo#

Laissez le chemin de contenu Hugo porter l’URL canonique chaque fois que possible.

• Utilisez _index.*.md pour les pages de section et les pages de branche
• Utilisez des paires name.en.md et name.fr.md pour les pages régulières bilingues
• Utilisez slug: pour les segments d’URL finaux localisés ou plus propres
• Utilisez aliases: lorsqu’une ancienne URL doit continuer de fonctionner
• Évitez url: sauf si l’URL ne peut pas s’exprimer proprement par le chemin de contenu

Dans un dossier de sujet, ne répétez pas le sujet dans chaque nom de fichier. Le dossier porte déjà ce contexte.

Préférez :

content-brand/docs/site-governance/naming-conventions.en.md
content/blog/files/naming-convention.en.md

Évitez :

content-brand/docs/site-governance/principles-and-rules-naming-conventions.en.md
content/blog/files/file-naming-convention.en.md

Gabarits, partials et classes#

Nommez le code réutilisable selon le patron qu’il implémente.

• Un partial utilisé par plus d’un site devrait porter un nom partagé, pas un nom propre au site de marque
• Une classe CSS devrait décrire le composant ou le patron, pas la première page qui l’a utilisée
• Un nom ponctuel peut commencer avec un nom propre à une page, mais il faut le renommer avant de le réutiliser ailleurs
• La documentation et le code devraient utiliser le même vocabulaire

Exemples :

Scripts#

Utilisez des noms de scripts npm qui décrivent la cible et l’action.

• dev est le serveur de développement par défaut du site principal
• dev:brand lance le serveur de développement du site de marque
• build:main et build:brand compilent chacun un site
• index:main et index:brand génèrent chacun un index Pagefind

Utilisez la forme verbe:cible lorsque l’action se répète sur plusieurs cibles. Gardez les noms assez prévisibles pour être devinés avant d’ouvrir package.json.

Clés d’archétypes#

Les fichiers d’archétype vivent dans archetypes/ et utilisent le kebab-case en minuscules. Nommez chaque clé selon la forme de contenu qu’elle crée, pas selon l’endroit où elle a d’abord été nécessaire.

• Utilisez un préfixe de site seulement lorsque la forme est propre à un site : brand-docs-page
• Utilisez un suffixe de format lorsque le même sujet a une forme de branche et une forme de feuille : docs-section, docs-page
• Utilisez des noms de domaine pour les objets documentaires réutilisables : component, shortcode, legal-page
• Évitez les noms qui décrivent le workflow plutôt que le résultat : utilisez blog-post, pas new-draft

La bibliothèque actuelle est :