Skip to content

Developers · Pages and Layouts

Developer layouts

Last updated 7 November 2026

Wrap every page in a shared frame: create layouts, choose one per page and pass content into it.

A layout is the frame around your pages. It holds the parts every page shares: the <html> and <head>, your stylesheet, the header, the footer and navigation. Each page supplies only its own content, and the layout wraps it.

How a layout wraps a page

  1. The page runsIts Liquid, GraphQL and partials produce its output.
  2. The output becomes content_for_layoutNamed content_for blocks are kept for later.
  3. The layout rendersIt prints the page output and fills each yield slot.
The layout is the outer layer of every HTML page.

Create a layout

Layouts live in app/views/layouts/. The default is application.liquid, which every page uses unless it names another. Print {{ content_for_layout }} exactly once where the page should appear:

app/views/layouts/application.liquid

<!DOCTYPE html>
<html lang='en'>
<head>
  <meta charset='utf-8'>
  <title>{{ context.page.metadata.title | default: 'My site' }}</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>

Choose a layout for a page

app/views/pages/dashboard.liquid

---
slug: dashboard
layout: admin
---

layout: admin uses app/views/layouts/admin.liquid. Set layout: '' for no layout at all, for example on a JSON endpoint.

Send page content to the layout

A page fills a named slot with content_for, and the layout prints it with yield:

{% content_for 'head' %}
  <link rel='stylesheet' href='{{ 'styles/dashboard.css' | asset_url }}'>
{% endcontent_for %}

Example: list the layouts on an instance

Query

{
  admin_liquid_layouts(per_page: 10) {
    total_entries
    results { path }
  }
}

Response on the docs instance (shortened)

{
  "data": {
    "admin_liquid_layouts": {
      "total_entries": 13,
      "results": [
        { "path": "modules/insites_crm/external_email_layout" },
        { "path": "modules/website/docs_layout" }
      ]
    }
  }
}

This ran read-only on the docs.insites.io instance on 1 November 2026, which has 13 layouts. Layouts from modules carry the module path in their name.

Common mistakes

  • No {{ content_for_layout }} in the layout. The page content does not appear.
  • No application layout on a new instance. A page on the default layout still answers 200, but with no frame. Any other missing layout name is refused when the page is saved.
  • A yield name that does not match the content_for name. The slot renders nothing.
  • A blank name in the CMS list. Set metadata.layout_name on the layout record when a readable name matters.