Page metadata

Page metadata allows themes to expose configuration for individual pages.

Just like theme tokens, page metadata is declared using JSON and automatically becomes editable through the Masthead editor. The difference is that metadata belongs to a single page instead of the entire site.

This makes page metadata ideal for values that change from page to page while still being defined by the theme.

Declaring page metadata

Page metadata is declared in the metadata section of the theme manifest.

{
  "metadata": [
    {
      "key": "hero_title",
      "label": "Hero title",
      "type": "string",
      "default": ""
    }
  ]
}

Every page created on the site now exposes this field.

Like theme tokens, page metadata supports all available field types, including objects and lists.

Accessing metadata

Metadata is available through the page.metadata object.

<h1>{{ page.metadata.hero_title }}</h1>

Unlike theme tokens, metadata only exists on the page currently being rendered.

Site-wide vs page-specific

Theme tokens and page metadata solve similar problems, but at different levels.

Use theme tokens for values shared across the entire site.

Examples include:

• Brand colours
• Navigation
• Footer content
• Contact information
• Typography

Use page metadata for values that belong to a specific page.

Examples include:

• Hero titles
• Featured images
• Layout options
• Sidebar visibility
• Landing page content

As a general rule:

• If changing the value should affect the entire website, use a theme token.
• If changing the value should only affect a single page, use page metadata.

Categories

Like theme tokens, page metadata can be grouped using categories.

{
  "key": "hero_title",
  "category": "Hero"
}

Categories organize the editor and have no effect on rendering.

Field types

Page metadata supports the same field types as theme tokens.

• String
• Text
• Number
• Length
• Boolean
• Color
• URL
• Select
• File
• Object
• List

This means the same configuration patterns can be reused throughout a theme.

Choosing the right type of metadata

Global page metadata is shared by every page in a site.

When a setting only applies to a specific page template, it’s usually better to define it as theme page metadata instead. This keeps the editor clean and only exposes settings where they’re relevant.

Theme page metadata is covered later in this guide.

Next steps

So far, every example has used simple values such as strings and colours.

Many themes require more structured configuration, such as navigation menus, social links or grouped settings. The following guides introduce objects and lists, the building blocks used to model this type of data.