Front matter

The block between --- markers at the top of a content file is its front matter. It stores the metadata that describes or augments the content: title, dates, draft status, aliases, URL, and other values that control how Hugo places the page in the site. Hugo accepts three formats — YAML with ---, TOML with +++, JSON with {} — and pages here use YAML.

---
title: "Front matter"
date: 2026-05-10
lastmod: 2026-08-15
description: "The metadata contract for content files"
---

The keys#

Omit fields that only restate defaults. Do not add draft: false, sitemap_exclude: false, description: "", tags: [], or empty aliases: values. Reserve draft: false for examples that explicitly show Hugo’s draft states.

Dates#

• date: first publication date
• lastmod: meaningful editorial or content update

Front matter is the source of truth for dates, not Git. Git dates can change during migrations, rebases, bulk formatting, file moves, or deployment clones; Git info is useful as a fallback or audit signal only. Front matter is intentional and clearer for bilingual publishing.

Slugs and URLs#

Publication dates stay out of URLs. Date URLs suit news and time-bound publishing; evergreen working notes get updated, and a date in the path makes updated content feel stale. The rule for permanence: keep stable slugs, avoid changing them casually, and add aliases whenever a slug does change. That gives durable URLs without locking the publication date into the path.

slug changes the last segment of a regular page URL. On a multilingual site, that lets a translation have a localized permalink without breaking the translation relationship:

# content/about.en.md
---
title: "About"
translationKey: "about"
---

# content/about.fr.md
---
title: "À propos"
slug: "a-propos"
translationKey: "about"
---

With defaultContentLanguageInSubdir = true, Hugo builds /en/about/ and /fr/a-propos/. Without that setting, Hugo’s default-language URL may be /about/ instead. The translation link still works because both pages share the same translationKey.

The localized slug is the page’s primary URL. Hugo does not automatically make /fr/about/ an alias of /fr/a-propos/. Add one explicitly when the old path needs to redirect:

aliases:
  - "/fr/about/"

For section pages such as _index.md, slug can localize the section path while preserving the shared content structure:

# content/legal/_index.fr.md
---
title: "Mentions légales"
slug: "mentions-legales"
aliases:
  - "/fr/legal/"
---

Use url only when slug and file placement cannot express the route cleanly. url overrides the whole path and takes precedence over slug, so use it deliberately.

Translations#

For bilingual pages, identical filenames link translations automatically:

content/docs/site-governance/content/example.en.md
content/docs/site-governance/content/example.fr.md

If the filenames, titles, or slugs differ, use the same translationKey in both files:

# content/docs/site-governance/content/hello.en.md
---
title: "Hello World"
translationKey: "hello-post"
---

# content/docs/site-governance/content/bonjour.fr.md
---
title: "Bonjour le monde"
translationKey: "hello-post"
---

The translationKey values must match exactly. It overrides filename-based linking, so Hugo can connect two files with unrelated names as translations.

Aliases#

On a multilingual site, include the language prefix when the old URL is language-specific:

aliases:
  - "/en/hello/"
  - "/fr/bonjour/"

Use a root alias such as /hello/ only when that old URL truly existed at the root or should redirect from the root. If the page lives under /en/hello/, prefer /en/hello/ for language-specific redirects.

related#

related: lists language-agnostic paths that render as a related list after the content. The identical list goes in both language files. Rendering behaviour, build-time warnings, and the choice between related: and the other pointer mechanisms are covered in cross-references.

Pattern pages#

Pattern pages use the pattern_* fields only under docs/site-implementation/patterns/. They record a recurring task’s category, status, component composition, content or data requirements, composition-level accessibility expectations, verified implementation evidence, and related patterns. Keep composition and evidence paths identical in both language files; translate the reader-facing content and accessibility lists.

Use Pattern library to decide whether a task merits a pattern. Use Pattern library for the complete field contract and validation command.

Brand documentation scope#

Use docs_metadata_scope when a brand documentation page is the public lookup surface for a rule that also has a governance page, implementation page, or both. The docs title block renders the page date with compact links to those companion pages.

docs_metadata_scope:
  governance: /docs/site-governance/glossary
  implementation: /docs/site-implementation/architecture/glossary-generation

Do not use this field for ordinary related reading. Use it only when the linked pages define ownership or implementation details for the current page.