Rendering blocks

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

This guide assumes you have a template and at least one block file.

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, the object type is page. In an event template, it is 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

To override the template for a specific block type, add blockType:template/path.liquid after the object type:

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

For blocks with blockType of text-section, this uses blocks/custom-text.liquid instead of the default blocks/text-section.liquid.

Separate multiple overrides with commas:

{% 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>

The corresponding .liquid file in blocks/ renders each block. Unless you specify an override, the tag resolves the path as blocks/[blockType].liquid.

stageblocks automatically injects an anchor ID into the first anchorable HTML element (section, div, article, header, footer, main, aside) in each block's output. The ID comes 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>

Basker resolves relationship fields used by the active template into public document objects rather than bare IDs. Referenced nested fields are available through dot notation, so an event block can read block.event.venue.title directly. Check optional properties before you render them. 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. stageblocks wraps the output in:

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

stageblocks limits recursion depth 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.richDescription_html %}
    <div class="event__description rich-text">
      {{ event.richDescription_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: The editor controls the order, 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.