Skip to content

Designers · Build with the Library

Page layouts

Last updated 18 November 2026

Build the HTML shell your pages share, and choose it for each page in the CMS.

Developers · Designers

A layout is the HTML shell that wraps your pages. It holds the head, the header, the footer and the shared styles. Each page fills in only its own content.

How a layout works

  1. A visitor opens a pageThe page runs its own Liquid
  2. The page output is keptAs content_for_layout
  3. The layout wraps itAnd sends the full HTML
How a page and its layout make one HTML response

The layout places the page where it writes {{ content_for_layout }}. Pages use the layout called application unless they choose another one.

app/views/layouts/application.liquid

<!DOCTYPE html>
<html lang='en'>
<head>
  <meta charset='utf-8'>
  <meta name='viewport' content='width=device-width, initial-scale=1'>
  <title>{{ context.page.metadata.title }}</title>
  <link rel='stylesheet' href='{{ 'styles/main.css' | asset_url }}'>
  {% yield 'head' %}
</head>
<body>
  {% render 'shared/navigation' %}
  {{ content_for_layout }}
  {% yield 'footer_scripts' %}
</body>
</html>

Slots for page-specific extras

A layout can leave named slots with {% yield 'head' %}. A page fills a slot with {% content_for 'head' %}. Use this when one page needs its own styles or scripts but the same shell.

Where layouts live

  • A site's layouts go in app/views/layouts/.
  • Layout file names use snake_case, for example dashboard_default.liquid.
  • A page chooses a layout in its front matter, for example layout: dashboard_default. A layout inside a module is named with its module path.

Create a layout in the CMS

  1. In your site admin, open CMS, then Layouts.
  2. Choose Create Layout and give it a Layout Name.
  3. On the Content tab, paste the layout HTML. Place {{ content_for_layout }} where page content should go.
  4. Save with a commit message that says what changed.
  5. Open a page in CMS, Pages, and choose your layout in the Layout field.

Tip

Most sites need two or three layouts: one for public pages, one for signed-in areas and a plain one for sign-in screens. Use partials, not new layouts, when only the header changes.