The cascading directories of a Shopify theme


1 | Level 1: the templates directory


Here is a table listing the default template files and the naming convention to use for creating alternate templates. I have regrouped the templates by using my own unofficial categories.


Unofficial categoriesDefault template filesNaming convention for alternate templates
Commerceproduct.liquidproduct.___.liquid
Commercecollection.liquidcollection.___.liquid
Commercelist-collections.liquidlist-collections.___.liquid
Commercegift_card.liquidgift_card.___.liquid
Commercecart.liquidcart.___.liquid
General contentarticle.liquidarticle.___.liquid
General contentblog.liquidblog.___.liquid
General contentindex.liquidindex.___.liquid
General contentpage.liquidpage.___.liquid
Customersaccount.liquid../account.___.liquid
Customersactivate_account.liquidactivate_account.___.liquid
Customersaddresses.liquidaddresses.___.liquid
Customerslogin.liquidlogin.___.liquid
Customersorder.liquidorder.___.liquid
Customersregister.liquidregister.___.liquid
Customersreset_password.liquidreset_password.___.liquid
Other404.liquid404.___.liquid
Otherpassword.liquidpassword.___.liquid
Othersearch.liquidsearch.___.liquid

1.1 | My comments


  • Any Shopify theme has or should have at least the 19 default template files listed above to work properly.
  • You can create additional templates, called alternate templates by Shopify. The only constraint is to abide by the naming convention. The name of the alternate template must replace the ___.
  • Shopify determines the page type of the template file by looking at the beginning of the file name, precisely between the first letter and the first dot that is in the name of the file.
  • You can change the template linked to a URL in the Shopify admin. The option to change the template only appears if there are at least 2 template files beginning with the same identifier.
  • Never ever change the name or delete the default files of a theme. It might cause 404 errors.
  • The index.liquid template file is for designing the home page of a Shopify store. It must include the Liquid tag {{ content for index }}. This tag enables us to add sections to our home page directly in the Theme editor in the Shopify admin (Online store -> Themes -> Customize). For a section to be eligible for the home page, it must have a presets property defined in its schema. We will come back to this later.

1.2 | Example: how to create an alternate template?


Let’s say that we own the Shopify store "Dog Paradise", that sells food for dog to dream about (Yes, the food is that good!). Our live theme in our store is the Debut theme, available for free at https://themes.shopify.com/. We have the annual Doggy festival coming next year, where the most influential dogs on social media are invited to party around nice sausages. We have created a new page in the Shopify admin (Online Store > Pages) called Doggy festival 2022 with the URL handle doggy-festival-2022. This event is so special that we need a custom template for it, different from the one the Debut theme uses. How can we proceed?


  1. First, in the Shopify admin, we duplicate our Debut theme and call it Debut Altered 1. By duplicating our theme, we can test our soon-to-be-altered theme safely, without risking breaking our live theme (theme in production).
  2. We go to the Edit code part of our theme, in the Templates folder. We create a new template, by clicking on Add a new template. We create a new template for page called festival. Shopify will automatically create the file page.festival.liquid. We now have 2 templates for our "page" pages (unfortunate but inevitable repetition): page.liquid, the default template for the original Debut theme, and page.festival.liquid, our 1st alternate template.
  3. We can now modify our page.festival.liquid file. We can add some HTML and CSS to make the page look irresistible to dog owners. Once we are done, we save the changes.
  4. In the Shopify admin, we create a page called Doggy festival 2022. On the right-hand side of the screen (on a desktop), there is a Template box with a dropdown menu. We can choose which template we want to use for our Doggy festival 2022 page. Note that the names of the template appear without the .liquid extension. We change the template from the default one, page , to our custom template, page.festival.
  5. We preview our site to see if everything is OK. If it is, we can then put our Debut Altered 1 theme live.

2 | Level 1: the layout directory


From my experience, you rarely have to create a new layout file, since the default layout file, theme.liquid, is quite generic. It is that generic because, by default, a single layout file is used to render all pages of the store. Let’s have a closer look at the theme.liquid file. It has 2 layers of code:


  1. The 1st layer contains the information required between the opening and closing HTML tags <head></head>. This layer must always contain the Liquid tag {{ content_for_header }}. This tag is mandatory and required by Shopify. It automatically uses the information of the Online Store > Preferences section of the Shopify admin. This includes the Google Analytics tag and the Facebook Pixel.
  2. The 2nd layer contains the code for the rest of the page. It is quite common to have the Liquid tags {% section 'header' %} and {% section 'footer' %}, to embed the appropriate sections for the header and the footer of every page of the store. There is also another mandatory Liquid tag required by Shopify: {{ content_for_layout }}. It must be placed between the opening and closing HTML tags <body></body>. This tag automatically embeds the content of the right template file. Remember that every template file must specify on its 1st line which layout file to use. If the {% layout %} Liquid tag is not there, then Shopify uses, as a fallback, the default theme.liquid file.

3 | Level 2: the sections directory


Sections are clearly the most powerful feature of Shopify themes. There are simply pieces of code that can be embedded and referenced in a layout file or a template file. But you can also make sections directly editable in the Shopify admin, within the Shopify theme editor. They are the only files in Shopify that have this feature. This is very convenient if you want to create zones that can be easily changed directly in Theme > Customize.


A section file can be divided into 2 parts:


  • The first part contains standard HTML and Liquid code.
  • The second part is the schema of the file. The schema is a JSON object that lists all editable zones that can be referenced in the first part of the file. The JSON object also creates a tab in the theme editor that enables direct changes by going to Theme > Customize.

Example


In our Dog Paradise shop, we want to create a section to showcase the name and the picture of the dog of the year. We will add this section in our Doggy festival 2022 page.


Step 1. We create a new section file called dog-of-the-year.liquid with a simple h2 tag containing the dog name and an img tag for the picture of the dog. For now, we leave them empty.

<!-- Example 4.1 -->
<h2></h2>
<img src = "" alt = "">
{% schema %}
  {
  "name": "Section name",
  "settings": []
  }
{% endschema %}

Any schema (JSON object) must have a "name" property. In the previous code, the schema part of the file was generated automatically by Shopify when we created the file. We deleted some other Liquid tags that we would not use here: ( {% javascript %} and {% stylesheet %} ).


Step 2. In the schema part of the file, we create a text element and an image element. For that, we check the Shopify documentation at https://shopify.dev/docs/themes/settings to see how to create text and image elements in the JSON object. The nature of the element is defined by the "type" property. In our case, we create an element (object) with the property "type": "text" and another element (object) with the property "type": "image_picker". We also change the name of our JSON object from "Section name" to "Dog of the year".


<!-- Example 4.2 -->
<h2>{{ section.settings.dog_name }}</h2>
<img src="{{ section.settings.dog_picture | img_url: '500x500' }}"
alt="Picture of the dog of the year">

{% schema %}
  {
  "name": "Dog of the year",
  "settings": [
    {
    "type": "text",
    "id": "dog_name",
    "label": "Dog's name"
    },
    {
    "type": "image_picker",
    "id": "dog_picture",
    "label": "Picture of the dog of the year"
    }
  ]
  }
{% endschema %}

Step 3. We add the Liquid variables so that the elements we defined in the schema part of the file can be displayed on the final web page. We use the Shopify Liquid Cheat Sheet ( https://www.shopify.com/partners/shopify-cheat-sheet ) to make sure that our Liquid code syntax is correct. To display the URL of the picture we would upload in the theme editor, we need to use the Liquid filter img_url. To reference the elements we created in the schema part, we use their id property. In a section file, the JSON object is stored in the section variable.


<!-- Example 4.3 -->
<h2></h2>
<img src="" alt="">

{% schema %}
  {
  "name": "Dog of the year",
  "settings": [
    {
    "type": "text",
    "id": "dog_name",
    "label": "Dog's name"
    },
    {
    "type": "image_picker",
    "id": "dog_picture",
    "label": "Picture of the dog of the year"
    }
  ]
  }
{% endschema %}

Step 4. Last, we can add the Liquid tag {% section 'dog-of-the-year' %} in the page.festival.liquid file, so that our section appears in the Doggy festival 2022 page. Now, when we go to Theme > Customize in the Shopify admin, and we select the Doggy festival 2022 page in the dropdown menu, there is a new section called Dog of the year. As expected, we can edit the name and the picture of the dog of the year.


Sections are quite flexible. The best way to learn how to use them is through practice. Also, you will have to regularly go to these 3 pages:



My comments:


  • The schema part of a section file, enclosed between the opening and closing Liquid tags {% schema %}{% endschema %}, is a JSON object. As humans, we are not good at parsing JSON. Watch out for commas, closing brackets, and closing curly braces. It is easy to make a syntax error by forgetting one of these characters. Gladly, the Shopify theme editor checks the validity of the file before we can save it. If you are working on files on your local computer or on a Cloud IDE, be extra careful about this.
  • Even if the schema part of a section file can be anywhere in the file, the best practice is to always put it at the bottom of the file.

4 | Level 3: The snippets directory


As their name indicates, snippets files are small pieces of code that can be embedded or referenced in any file from any cascading directory on top of them.


The modern way to embed or reference a snippet into another file is to use the {% render %} Liquid tag. Indeed, the former {% include %} tag is being deprecated in favor of the new {% render %} tag.


So far, even if we have not mentioned it until now, any "child" file that is referenced or embedded into a parent file has automatically access to all variables and objects of the parent file.


In that regard, snippets referenced with {% render %} behave differently. They have a very strict scope: you must pass variables to them so that they can be used within the snippet code. Shopify opted for this encapsulation principle to increase performance and to make theme code easier to understand and maintain. Hence the introduction of the new {% render %} tag, to replace the {% include %}, which allowed direct access to variables of the parent file.


You can see how to pass variables to a snippet in the Shopify documentation directly here: https://shopify.dev/docs/themes/liquid/reference/tags/theme-tags#passing-variables-to-a-snippet.


5 | Level 4: the assets directory


When you want to reference an asset file, you must use of the 3 following Liquid filters:


  • asset_img_url.
  • asset_url.
  • img_url.

All files you upload on Shopify are stored in the assets directory.


Author: (reviewed by Coralie Delpha)
Initial publication date:
Last updated: