Front matter

Front matter is the machine-readable metadata at the top of each Markdown file. Governance defines which fields authors may use; architecture defines how templates consume those fields.

Use Site governance > Content > Front matter for authoring rules. Use this page when adding template behaviour, section archetypes, or metadata-driven indexes.

Page metadata#

Every documentation page starts with the same stable shape:

title: "Anchor index"
date: 2026-08-11
lastmod: 2026-08-17
description: "A labeled row of compact links that jumps to repeated page sections"
weight: 10
related:
  - /docs/site-implementation/components/filter-row/

Templates use those fields for titles, descriptions, sorting, related links, search metadata, language alternates, and generated overview tables.

Interface manifests#

Components and shortcodes use one metadata contract. It keeps each canonical section focused on its audience while allowing generated indexes and a future unified inventory to read the same fields.

interface_kind: "component"
interface_category: "navigation"
interface_status: "implemented"
interface_implementation:
  partial:
    - layouts/partials/data-page/anchor-index.html
  css:
    - assets/css/site.css
  i18n:
    - airlineCodesAnchorIndexLabel
interface_consumers:
  - layout: layouts/partials/docs/shell.html
  - site: main
    page: /blog/ref/airline-codes
    label_key: interfaceConsumerAirlineCodes

Use layout for a source layout that consumes the interface. Use site, page, and label_key for a rendered page; label_key is required when that page is on another site.

interface_kind is component or shortcode. Components also carry an interface_category, such as navigation, action, content, data, layout, or utility. interface_status is specified, implemented, or deprecated.

interface_preview records an exception to the normal framed or direct example. Use page when the current page shell renders the component, render-hook when a Markdown render hook produces the example, or consumer when another page supplies the required data or composition. A consumer record also declares interface_preview_page and links to that page with component-relationship. Omit both fields when the documentation already contains component-preview, direct component markup, or an active implementation shortcode.

interface_implementation is an evidence map. Its keys are the mechanisms used by the interface: partial, shortcode, layout, data, css, js, i18n, or configuration. Each value lists the relevant source files; for i18n, it lists the static keys read directly by the interface. This keeps the mechanism and its evidence together and makes the manifest useful to both people and validation. related_interfaces contains documentation paths for a related component or shortcode; omit the field when no relationship exists.

Use only the mechanisms present in data/interfaces.yml. Include only verified files and static keys; do not repeat page prose as metadata. interface_source is a legacy compatibility field for records that have not yet been audited. Do not add it to new or updated records.

Use immediately before the ## Accessibility heading. It renders a ### Interface manifest description list from these fields; do not duplicate it in page prose. The fields back the grouped Components index and will become the source of truth for any future filtered inventory.

Pattern manifests#

Patterns use a parallel pattern_* contract because they record compositions rather than one interface unit. It keeps the task, constituent components, content and data needs, composition-level accessibility, and implementation evidence machine-readable without overloading component metadata.

Use Pattern library for the field shape, page recipe, generated {{< pattern-manifest >}}, and npm run lint:patterns validation. Use Pattern library for the decision boundary.

Folder shapes#

The recurring folder shapes are stable and backed by Archetypes when a starter file is useful:

Use a physical archetype when a pattern repeats often enough that manual copying creates drift. Copy the nearest published page only when the new page needs unusually specific content or behaviour.

Tables With Rich Cells#

Plain Markdown tables are preferred. Use inline HTML inside a table cell only when the content needs structure that Markdown tables cannot express cleanly.

Allowed for occasional use:

<br />
<ul>
  <li>Hugo partial ← <code>layouts/partials/data-page/anchor-index.html</code></li>
  <li>CSS ← <code>assets/css/site.css</code></li>
</ul>

Use a partial or shortcode when the same rich table shape appears more than once. A repeated pattern should not depend on hand-written HTML in every Markdown file. Good candidates are component profile tables, option tables, and implementation source lists.