Layouts

Layouts are wrapper templates that surround your page content. They hold the outer HTML structure that stays consistent across pages: the tag, section, headers, footers, and navigation. Without layouts, every page would duplicate this code.

How Layouts Work

Each layout is a Liquid file in the directory. Pages reference their layout by name in the YAML front matter. The layout wraps the page content using the tag, which is replaced with the rendered page content at runtime.

The default layout is . If a page does not specify a layout, the layout is used automatically. You can change the default in config.yml using the flag.

Creating a Layout

You can create layouts through the Instance Admin UI or via code.

Via code:

1. Create a new file in (e.g., ).
2. Add your HTML structure with the placeholder where page content should appear.
3. Reference the layout from pages using the property in the YAML front matter.

Via Instance Admin:

1. Navigate to CMS in the main menu.
2. Select Layouts.
3. Click Add Layout and provide a name and content.

Assigning a Layout to a Page

Set the property in a page's YAML front matter to specify which layout to use:

To render a page without any layout (e.g., for API endpoints or AJAX responses), set layout to an empty string:

Injecting Dynamic Content

Use the and tags to inject page-specific content into named regions of a layout. This is commonly used for per-page metadata, stylesheets, or JavaScript files.

In the page:

In the layout:

The tag accepts an optional default value that is used when the page does not define content for that region.

Multiple Layouts

You can create as many layouts as your application needs. Common patterns include:

• application - the default layout for public-facing pages
• admin - a separate layout for admin or dashboard pages with different navigation
• mailer - a layout for email templates (used with the email notification system)
• empty - a minimal layout with no wrapping, useful for embeddable widgets