Partials

Like most liquid templating environments, you can organize and reuse templates by creating partials. To indicate that a liquid template is a partial, prefix the name with an underscore. This will prevent the file from being rendered as its own html file, and enable it to be used as a partial.

For instance, you could define a file called _video.liquid like this:

{% if video.url != "" %}
  <video title="{{video.name}}" controls>
    <source
      src="{{video.url}}"
      name="{{video.filename}}"
      type="{{video.mime}}">
  </video>
{% endif %}

Then, in a page template you can use this partial:

<h3>{{object.name}}</h3>
{% include 'video' video: object.video %}

Partials may be defined in the pages dir directly or as subpaths (e.g. pages/partials/_video.liquid could be rendered using {% include 'partials/video' video: object.video %})

Archival supports two tags for rendering a partial: include, which shares the current template's variables, and render, which renders the partial in an isolated scope. Both accept the same arguments.

Both include and render accept any number of key: value arguments, which become variables inside the partial. Arguments may be separated from the partial name by a comma or by whitespace, and a trailing comma is allowed:

{% include 'video' video: object.video, autoplay: true %}
{% include 'video', video: object.video, autoplay: true %}

You can also pass a single value with with, binding it to a name with as:

{% render 'card' with post as card %}

If you leave off as, the value is bound to the partial's name. For a partial in a subdirectory, only the last path segment is used — {% render 'partials/card' with post %} binds the value to card.

To render a partial once per item in a list or range, use for:

{% render 'card' for posts as post %}
{% render 'card' for (1..3) as index %}

Inside a for, the partial also gets the usual forloop variable, and a {% break %} in the partial stops the iteration.

Extra key: value arguments can be combined with either clause, and are passed to every iteration of a for:

{% render 'card' for posts as post, show_date: true %}

{% include %} renders the partial with the current scope: everything visible to the including template — including variables it has assigned and loop variables — is visible inside the partial, and variables the partial assigns remain set afterwards.

{% render %} renders the partial in an isolated scope. The partial sees only:

• the arguments passed to it, and
• your site's global variables — objects, the pluralized object accessors, site_url, page, and (on a page template) the object being rendered.

The calling template's local variables are not visible, and anything the partial assigns does not leak back out. Referencing a variable that wasn't passed is an error rather than silently rendering empty:

{% assign heading = 'Recent posts' %}

{% include 'header' %}  <!-- sees heading -->
{% render 'header' %}   <!-- errors: heading was not passed -->
{% render 'header' heading: heading %}  <!-- sees heading -->

Prefer render for partials you want to be self-contained — it makes their inputs explicit and keeps them from being broken by unrelated changes to the templates that use them. Use include when a partial is intentionally coupled to its caller's scope.

Globals stay available no matter how deeply partials are nested, so a partial rendered with render can itself render another partial and still reach your objects:

{% for post in posts %}
  {% render 'card' with post %}
{% endfor %}