Theme Pages

Theme pages allow themes to define custom page templates together with their own editing experience.

Unlike regular pages, which all share the same global page metadata, each theme page can expose configuration that only applies to that specific template. This keeps the editor focused and prevents unrelated settings from appearing on every page.

Creating a theme page

Theme pages live inside the templates/pages directory.

Each theme page consists of two files:

templates/
  pages/
    home.liquid
    home.json

The .liquid file defines how the page is rendered.

The accompanying .json file defines the editor shown to the site owner.

Both files must share the same name.

Rendering a theme page

When creating or editing a page, Masthead allows the site owner to select one of the available theme pages.

Once selected, Masthead renders the corresponding Liquid template instead of the default page.liquid template.

The page’s metadata is then made available to the template through the page.metadata object.

Theme page metadata

Theme page metadata is declared inside the page’s JSON sidecar file.

The schema is identical to theme tokens and global page metadata, supporting the same field types including objects and lists.

{
  "label": "Homepage",
  "metadata": [
    {
      "key": "hero",
      "label": "Hero",
      "type": "object",
      "fields": [
        {
          "key": "title",
          "label": "Title",
          "type": "string"
        }
      ]
    }
  ]
}

Masthead automatically generates the editor from this schema.

Choosing the right configuration

Masthead provides three different levels of configuration.

Use…	When…
Theme tokens	The value belongs to the entire site.
Global page metadata	Every page should expose the value.
Theme page metadata	The value only makes sense for a specific page template.

Choosing the appropriate level keeps themes easier to understand and avoids exposing unnecessary settings to site owners.

Reusable page templates

Theme pages make it possible to build reusable layouts for common website sections.

For example, a theme could provide templates for:

• Homepage
• Documentation
• Pricing
• Portfolio
• Landing page

Each template can expose exactly the configuration it needs while sharing the same styling and layout as the rest of the theme.

Next steps

Theme pages define the structure and configuration of a page, but the templates themselves are written using Liquid.

The next guide introduces the variables and filters available while rendering a Masthead theme.