Page layouts

Page layouts are predefined collections of blocks that help creators quickly set up pages with a sensible structure. When a creator adds a new page to their site, they can choose from the available layouts to get started with a ready-made arrangement of blocks.

Location

Each page layout is defined as its own JSON file in the pages directory of the theme:

pages
├── homepage_1.json
├── landing_page_1.json
├── book_experiences.json
├── faq.json
└── story_and_team.json

Structure

A page layout file requires three properties, plus one optional flag:

Name

The page name is displayed when a creator is choosing a layout and becomes the name and slug of the page that is created.

Since slugs must be unique, if the slug is already in use it will be suffixed with a number (or the next available number). However, sites can have multiple pages with the same name.

Category

The category groups related page layouts together, making it easier for creators to browse and choose appropriate layouts. Categories are shown in alphabetical order in the page picker.

Developer-only layouts

Some layouts are useful while building a theme but aren't meant for creators — for example a block library page that renders every block in the theme for development and QA. Add "developer_only": true to hide a layout from the page picker for anyone without the developer or theme developer role:

{
  "name": "Block Library",
  "category": "Development",
  "developer_only": true,
  "blocks": [...]
}

Developers see these layouts in the picker as normal. For everyone else the layout is removed before layouts are grouped, so a category containing only developer-only layouts doesn't appear at all. Layouts without the flag are unaffected.

Blocks

Blocks are included in the page in the order they appear in the array. Each block entry requires a key matching a block defined in the theme's blocks directory.

By default, a block will use all its default attribute values. You can override these defaults by specifying an attributes object:

{
  "key": "hero_block",
  "attributes": {
    "heading": "My amazing page",
    "show_button": false
  }
}

When a creator selects a page layout, they see a preview of the page including any attribute overrides.

Example

For a file at pages/homepage.json:

{
  "name": "Homepage",
  "category": "Homepage",
  "blocks": [
    {
      "key": "hero_homepage_one"
    },
    {
      "key": "h3_header",
      "attributes": {
        "block_padding": { "padding_bottom": "3", "padding_top": "7" },
        "button_content": { "cta_text": "Learn more" }
      }
    },
    {
      "key": "image_single",
      "attributes": {
        "full_width": "false"
      }
    },
    {
      "key": "testimonials"
    }
  ]
}

This layout creates a page with a hero block at the top, a heading with customised padding, an image block, and a testimonials section — all using sensible defaults with a few targeted overrides.