Layout

v1.9.1

Using a Layout

Introduce a layout template for the current template to render in. The directory for layout files are defined by layouts or root.

// default-layout.liquid
Header
{% block %}{% endblock %}
Footer

// page.liquid
{% layout "default-layout.liquid" %}
{% block %}My page content{% endblock %}

// result
Header
My page content
Footer

If extname option is set, the .liquid extension becomes optional:

{% layout 'default-layout' %}

Scoping

When a partial template is rendered by layout, its template have access for its caller’s variables but not vice versa. Variables defined in layout will be popped out before control returning to its caller.

Multiple Blocks

The layout file can contain multiple blocks, each with a specified name. The following snippets yield same result as in the above example.

// default-layout.liquid
{% block header %}{% endblock %}
{% block content %}{% endblock %}
{% block footer %}{% endblock %}

// page.liquid
{% layout "default-layout.liquid" %}
{% block header %}Header{% endblock %}
{% block content %}My page content{% endblock %}
{% block footer %}Footer{% endblock %}

Default Block Contents

In the above layout files, blocks has empty contents. But it’s not necessarily be empty, in which case, the block contents in layout files will be used as default templates. The following snippets are also equivalent to the above examples:

// default-layout.liquid
{% block header %}Header{% endblock %}
{% block content %}{% endblock %}
{% block footer %}Footer{% endblock %}

// page.liquid
{% layout "default-layout.liquid" %}
{% block content %}My page content{% endblock %}

Passing Variables

Variables defined in current template can be passed to a the layout template by listing them as parameters on the layout tag:

{% assign my_variable = 'apples' %}
{% layout 'name', my_variable: my_variable, my_other_variable: 'oranges' %}

Outputs & Filters

When filename is specified as literal string, it supports Liquid output and filter syntax. Useful when concatenating strings for a complex filename.

{% layout "prefix/{{name | append: \".html\"}}" %}

Escaping

In LiquidJS, " within quoted string literals need to be escaped. Adding a slash before the quote, e.g. \". Using Jekyll-like filenames can make this easier, see below.

Jekyll-like Filenames

Setting dynamicPartials to false will enable Jekyll-like filenames, file names are specified as literal string. And it also supports Liquid outputs and filters.

{% layout prefix/{{ page.my_variable }}/suffix %}

This way, you don’t need to escape " in the filename expression.

{% layout prefix/{{name | append: ".html"}} %}