Naming conventions

Good names are boring in the useful way. They sort, survive migrations, and make each thing’s purpose easy to recognize later.

Use the strictest reasonable convention when a name may cross systems: macOS, Linux, Windows, Git, GitHub, SharePoint, OneDrive, Google Drive, archives, sync tools, and URLs. The long-form file naming article on BHDicaire.com carries the portability background; this page is the site rule.

General rule#

Use names that describe role and ownership, not the first page where the thing appeared.

• Prefer meaningful nouns: footer, docs-shell, data-page/table-wrap
• Prefer stable roles over page names: section-overview-table, not home-overview-table, when the pattern is no longer homepage-only
• Use lowercase kebab-case for files, folders, slugs, CSS classes, and most identifiers in content
• Avoid names that differ only by case
• Avoid spaces, emoji, punctuation-heavy names, and clever abbreviations
• Keep names short enough to stay readable in paths, URLs, terminals, and diffs

File and folder names#

Use this safe character set for portable file and folder names:

a-z 0-9 - _ .

Prefer kebab-case for content and code-adjacent files:

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

Use underscores only when they separate metadata blocks, especially in exported or archived files:

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

Keep the practical budget conservative:

Hugo content#

Let Hugo’s content path own the canonical URL whenever possible.

• Use _index.*.md for section and branch pages
• Use name.en.md and name.fr.md pairs for bilingual regular pages
• Use slug: for localized or cleaner final URL segments
• Use aliases: when an old URL must keep working
• Avoid url: unless the URL cannot be expressed cleanly through the content path

Inside a topic folder, do not repeat the topic in every filename. The folder already carries that context.

Prefer:

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

Avoid:

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

Templates, partials, and classes#

Name reusable code by the pattern it implements.

• A partial used by more than one site should have a shared name, not a brand-specific name
• A CSS class should describe the component or pattern, not the first page that used it
• A one-off name may start page-specific, but rename it before reusing it elsewhere
• Documentation and code should use the same vocabulary

Examples:

Scripts#

Use npm script names that describe the target and action.

• dev is the default main-site development server
• dev:brand runs the brand-site development server
• build:main and build:brand build one site each
• index:main and index:brand build one Pagefind index each

Use the verb:target shape when the action is repeated across targets. Keep names predictable enough that a contributor can guess them before opening package.json.

Archetype keys#

Archetype files live in archetypes/ and use lowercase kebab-case. Name each key by the content shape it creates, not the place where it was first needed.

• Use a site prefix only when the shape is site-specific: brand-docs-page
• Use a format suffix when the same topic has both branch and leaf shapes: docs-section, docs-page
• Use domain nouns for reusable documentation objects: component, shortcode, legal-page
• Avoid names that describe workflow instead of output: use blog-post, not new-draft

The current library is: