Master pages

Master pages are configurations of page sections and content sections that apply to multiple pages of the same type.

For pages which use master pages, the content of the page is the combination of the sections in the master page and in the page itself.

Master pages hold data for sections which will be rendered on a set of pages. For portability across themes, master pages exist independently of themes.

Rules for master pages

Each page resource of a type that supports master pages has a master_page_id property in the API, which determines how the page is rendered. Here are the rules associated with how master pages are rendered:

  • master_page_id is null by default.
  • When master_page_id is null, pages render the theme template.
  • When master_page_id is not null, pages render the master page instead of the theme template, even if template_suffix is not blank.
  • If you want to enable sections on a product, collection, article or custom page, you will therefore need to assign a master page to them.
  • When master_page_id is not null but the active theme does not have the corresponding page section, the page falls back to rendering using the theme template.
  • By default master pages only contain the page section, which can't be removed.

More details on master pages can be found in the Sections REST API documentation.

Pages which use master pages

  • Product
  • Collection
  • Custom page
  • Blog article

Customizing master pages

Master pages can be customized and populated with content sections through the Online Store editor. Only sections that exist in a theme’s content/ directory can be added to master pages.

Master pages are used by merchants to apply bulk changes to multiple pages at the same time. Merchants can also make page-specific overrides of master page configurations through the Online Store editor.