Rendering blocks

{% stageblocks %} renders the blocks attached to the current document. It iterates over the document's blocks array and renders each block using the matching .liquid file from blocks/.

Prerequisites

• A working page template (see Templates).
• Block files in blocks/ (see Blocks).

Steps

1. Add the stageblocks tag

Use {% stageblocks %} followed by the object type that matches the template's collection. The tag reads the blocks array from the current document and renders each in order.

{% stageblocks page %}

The object type must match the variable name for the current document. In a page template, page. In an event template, event.

2. Choose the correct object type

stageblocks supports the following object types:

An unsupported object type produces an HTML comment warning and no output:

<!-- Warning: Unsupported object type 'unsupported' for stageblocks -->

3. Use block type overrides

Override the template used for a specific block type by passing blockType:template/path.liquid after the object type:

{% stageblocks page, text-section:blocks/custom-text.liquid %}

This renders blocks with blockType of text-section using blocks/custom-text.liquid instead of the default blocks/text-section.liquid.

Multiple overrides are comma-separated:

{% stageblocks event, text-section:blocks/event-text.liquid, image-gallery:blocks/event-gallery.liquid %}

4. Understand the output structure

The stageblocks tag wraps all rendered blocks in a container <div>:

<div class="content-blocks">
  <!-- Each block renders here -->
</div>

Each block is rendered by its corresponding .liquid file in blocks/. The tag resolves the path as blocks/[blockType].liquid unless an override is specified.

An anchor ID is automatically injected into the first anchorable HTML element (section, div, article, header, footer, main, aside) in each block's output. The ID is derived from the block type and instance ID.

5. Understand block rendering context

Each block template receives:

• All template globals — every function and variable from the template context (tenant(), navigation(), settings(), etc.).
• The current document properties — all properties from the parent document.
• block — an object with the block instance data: id, blockType, and all flattened field values.

<section class="text-section">
  <h2>{{ block.heading }}</h2>
  <div class="rich-text">{{ block.body_html }}</div>

  <p class="text-section__tenant">{{ tenant().name }}</p>
</section>

Relationship fields are hydrated into full objects, not just references. A linked record's own properties — including its own relationships — are available through dot notation, so an event block can read block.event.venue.title directly. See Field types for the resolved shape of relationship and upload fields.

6. Handle reusable content blocks

When a document includes a reusable-content block, stageblocks automatically resolves and renders the referenced reusable content's blocks recursively. The output is wrapped in:

<section id="[block-id]" class="element reusable-content-block">
  <div class="reusable-content-block__inner">
    <!-- Nested blocks render here -->
  </div>
</section>

Recursion depth is limited to 10 levels to prevent infinite loops.

Complete example

A full templates/event.default.liquid using stageblocks:

<article class="event">
  <header class="event__header">
    {% if event.image %}
      <div class="event__hero">
        <img
          src="{{ event.image | image_url: width: 1400, height: 700, fit: 'cover' }}"
          alt="{{ event.image.alt | default: event.title }}"
          loading="eager"
        >
      </div>
    {% endif %}

    <h1 class="event__title">{{ event.title }}</h1>

    {% if event.venue %}
      <p class="event__venue">
        <a href="/venues/{{ event.venue.slug }}">{{ event.venue.title }}</a>
      </p>
    {% endif %}
  </header>

  {% if event.description %}
    <div class="event__description rich-text">
      {{ event.description_html }}
    </div>
  {% endif %}

  <div class="event__content">
    {% stageblocks event %}
  </div>
</article>

Troubleshooting

"stageblocks: No object type provided" — Add the collection name: {% stageblocks page %}.

"stageblocks: Unsupported object type" — Check the table in step 2 for valid values.

"stageblocks: No blocks found" — The document has no blocks. Add blocks in the editor.

Blocks render as HTML comments — A block template file is missing from blocks/. The output is <!-- Error rendering block [type]: ... -->. Create the matching .liquid file.

Blocks render in the wrong order — Order is controlled in the editor, not the template.

Related

• Blocks — creating block files.
• Block schema reference — field types and schema properties.
• Templates — template structure and schema.
• Template context — variables in block templates.