Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 23

Understanding the Template Hierarchy

Recommended resources

Hello and welcome back!

In the last lesson, we focused on the "Don't Repeat Yourself" (DRY) principle by creating a reusable product-card snippet. This gave us a powerful, component-like building block. Now, you might be wondering how these individual pieces—snippets, sections, and the templates we've built—all come together to form a complete, coherent webpage. How does Shopify know what to render, and in what order?

This lesson addresses that fundamental question. Our learning outcome is to explain the template hierarchy from layout files to specific page templates. We will deconstruct how Shopify renders a page, starting from the outermost HTML shell and working our way down to the specific content modules.

For someone with your background in Next.js, this concept is analogous to how a root _app.js or layout.tsx file provides the global structure (like the <html> and <body> tags and navigation), and then specific page components are rendered within that shell. Shopify's architecture follows a very similar, layered approach.

1. The Rendering Hierarchy: A Top-Down View

To manage complexity and separate concerns, Shopify themes use a clear hierarchy to construct pages. At the highest level, you have the master layout that defines the global page structure, and at the lowest level, you have small, reusable code blocks.

The official Shopify documentation provides a perfect summary of this structure.

Theme architecture

Let's start with the official definition. This page from the Shopify Developer documentation introduces the core components that determine the organization of each page. Pay close attention to the table.

Please read the section titled 'Markup and features'. The table in this section is the most important part, as it clearly lays out the hierarchy from the layout file down to snippets.

Here is a visual representation of that hierarchy, which helps to solidify the concept:

Shopify Theme Architecture Overview
This diagram illustrates the nested structure of a Shopify page. The Layout is the foundation, a Template defines the content for a specific page type, and Sections and Blocks are the modular components that fill the template.

To summarize the flow:

  1. Layout: The outermost shell. It contains the <html>, <head>, and <body> tags, and global elements like the header and footer.
  2. Template: The blueprint for a specific page type (e.g., product, collection). It gets injected into the layout.
  3. Sections: Reusable, merchant-customizable modules of content that are organized by the template.
  4. Snippets: (As we learned) Reusable pieces of code that are typically rendered within sections to build out the UI.

2. The Foundation: The layout Directory

Every page on your store starts with a layout file. This file acts as the master frame.

  • Location: layout/
  • Primary File: theme.liquid

The theme.liquid file is the default layout for almost every page. It contains the basic HTML document structure, links to your CSS and JavaScript files in the <head>, and typically includes your site's header and footer.

Two special Liquid tags are crucial for making this system work:

  • {{ content_for_header }}: This must be placed within the <head> tag. It's a required hook where Shopify dynamically injects critical scripts, including analytics and scripts needed by installed apps. Modifying this can break your store's functionality.
  • {{ content_for_layout }}: This is the magic placeholder. It must be placed within the <body> tag, usually inside a <main> element. This is where Shopify will inject the entire rendered content of the page-specific template.

To see this in context, let's review a clear explanation.

A Beginner's Guide to the Shopify Theme Structure

This article provides a concise and clear explanation of the layout folder and the critical roles of content_for_header and content_for_layout.

Read the section 'Layout' and pay close attention to the explanations for the two required Liquid tags. This will reinforce why they are non-negotiable parts of a theme.

Now, let's watch a video that walks through the theme.liquid file and demonstrates how content_for_layout works in practice.

Shopify Theme Development - Liquid Theme Architecture

The following video segment provides a code-level walkthrough of the layout directory and the content_for_layout variable.

Please watch from 11:50 to 14:50. The presenter clearly explains the role of theme.liquid as the default layout and demonstrates how moving the content_for_layout variable changes where the page's main content appears relative to other elements.

3. The Blueprints: The templates Directory

Once the theme.liquid layout is in place, Shopify needs to know what specific content to inject into the {{ content_for_layout }} placeholder. This is the job of templates.

  • Location: templates/

When a user visits a URL, Shopify maps it to a page type and looks for a corresponding template. For example, visiting /products/your-product-handle tells Shopify to use a product template.

In modern Shopify theme development (Online Store 2.0), there are two types of templates, and understanding their difference is crucial.

JSON Templates vs. Liquid Templates

  1. JSON Templates (.json): This is the modern standard. A .json template file isn't a markup file; it's a data file that specifies which sections to render on the page and in what order. This structure is what enables "Sections Everywhere," giving merchants the power to add, remove, and reorder sections on any page using the theme editor. The data for these sections is stored directly within the JSON template itself.

  2. Liquid Templates (.liquid): This is the legacy format. A .liquid template contains hardcoded HTML and Liquid, including {% section %} tags. Merchants have very little flexibility to reorder or add content. The data for sections used in Liquid templates is stored globally in config/settings_data.json, meaning a change to a section on one page could affect another page using the same section.

The following video provides an exceptionally detailed comparison of these two approaches. This is one of the most important concepts to grasp for modern theme development.

Shopify Theme Development - Liquid Theme Architecture

This is the most critical resource for this lesson. The presenter gives a masterclass on the templates directory, comparing and contrasting JSON and Liquid templates, how they are created, and where their data is stored.

Please watch from 44:30 to 1:04:45. This is a longer segment, but it is packed with essential information. Focus on: The purpose of templates and the different types (product, collection, page, etc.). The structure of a JSON template and how it maps to sections. The process of creating a new template through the UI and seeing the resulting .json file. The key differences in flexibility and data storage between JSON and Liquid templates.

Test your understanding!

A client has two types of blog posts: standard articles and "case studies". They want the case study posts to have a completely different layout, featuring a large hero image at the top and a customer quote section that won't appear on standard articles. The marketing team must be able to add/reorder these sections on the case study pages.

Which type of template (.json or .liquid) would you create for the "case study" layout, and why?

Show answer

You would create a JSON template (e.g., article.case-study.json).

Here's why:

  1. Flexibility for Merchant: The core requirement is that the marketing team can add and reorder sections. This is the primary advantage of JSON templates and the "Sections Everywhere" architecture.
  2. Alternate Template: You can create an alternate template for the same content type. By naming it article.case-study.json, you can then assign this specific template to your case study blog posts from the Shopify admin, while standard articles continue to use the default article.json template.
  3. Encapsulated Data: The layout and section data for the case studies will be self-contained within the article.case-study.json file, ensuring that changes made to the case study layout don't accidentally affect standard articles.

4. Putting It All Together: A Request Lifecycle

Let's trace a typical user request to see the hierarchy in action:

  1. A user navigates to a collection page, like /collections/winter-sale.
  2. Shopify's backend identifies this as a collection request.
  3. It loads the main layout file: layout/theme.liquid. The browser begins receiving the <head> section, including links to CSS files.
  4. Shopify looks for the template assigned to this collection. Let's assume it's templates/collection.json.
  5. The collection.json file contains a list of sections, for example, a collection-header section and a product-grid section.
  6. Shopify renders the Liquid code inside sections/collection-header.liquid and sections/product-grid.liquid in order. The product grid section might loop through the collection's products and use {% render 'product-card' %} for each one.
  7. The combined HTML output from all these sections is generated.
  8. This block of HTML is injected into layout/theme.liquid right where the {{ content_for_layout }} tag is located.
  9. The rendering of theme.liquid continues, adding the footer.
  10. The final, complete HTML document is sent to the user's browser.

Conclusion

You now have a complete mental model of how Shopify constructs a page from different file types. This "first principles" understanding of the rendering order is critical for knowing where to find and modify code effectively.

Key Takeaways:

  • A Page is a Nested Structure: The final HTML is built by nesting templates inside layouts. Layout -> Template -> Sections -> Snippets.
  • theme.liquid is the Master Shell: It provides the global HTML structure and includes the header and footer.
  • {{ content_for_layout }} is the Core Link: This tag is the crucial injection point where the page-specific template content is placed.
  • JSON Templates are the Modern Standard: They offer maximum flexibility for merchants by defining a page as a configurable list of sections.
  • Different Files for Different Concerns:
    • layout/: For the global page shell.
    • templates/: For the structure of specific page types.
    • sections/: For large, reusable, merchant-configurable content blocks.
    • snippets/: For small, reusable pieces of code logic and UI.

In this lesson, we confirmed where sections fit into the theme hierarchy. In our next lesson, we will dive deeper into what makes them so powerful. We will define a section's schema using a range of input settings (text, image_picker, color), which is the mechanism that allows merchants to customize their store's content and appearance directly from the theme editor.