Structure and content of a Shopify theme

1 | What is a Shopify theme?

A Shopify theme is a collection of dozens of files that are organized in 7 different directories. Some directories have a cascading relationship between them (I will call them the cascading directories) and some do not I will call them the flat directories). The cascading directories are fundamental for understanding how Shopify themes work. Please note the terms cascading and flat are not official terms from the Shopify documentation, but mine.

2 | How can we see the directories of a Shopify theme?

You can see all 7 directories of a Shopify theme in 2 different ways:

  1. By downloading a theme from the Shopify admin on a local computer (Theme -> Actions -> Download theme file), unzipping the folder and opening it with a code editor.
  2. By going directly to the code part of a theme (Theme -> Actions -> Edit code), in the Shopify admin. The name of the folders in the Theme editor of Shopify are almost the same as the name of the directories that you would see on a local computer.

Directories (local computer)Folders (Shopify admin)

3 | The flat directories

  • config. The config directory is meant to store the general settings related to a theme. These settings appear in the Theme settings area of the theme editor in the Shopify admin. This directory includes a settings_schema.json file and a settings_data.json file. The most useful file. The one that is meant to be edited by developers, is the settings_schema.json file.
  • locales. The locales directory stores all the translations for the default elements that can be used in any Shopify store. Each file of this directory stores the text for 1 language. The default language file used by Shopify, for the English language, is the en.default.json file. Even though it is possible to edit the files in the locales directory, we do not recommend that you do, because these changes can be made, in a safer way, through translations apps (Weglot , langify, Translation Lab to name a few).

4 | The cascading directories (Overview)

Shopify cascading directories Source

The cascading directories are the following:

  1. templates and layout.
  2. sections.
  3. snippets.
  4. assets.

What is the cascading principle?

Before Shopify sends a response back to the web browser to display a page to the visitor of the store, it parses all the required files. It starts from the 1st directories at the top of the cascade (templates and layout), and goes down to the last directory (assets) of the cascade.

Schematically, here is how it works:

  1. A visitor requests a page from a Shopify store. The request is sent to Shopify. Thanks to a pre-saved mapping, Shopify can match the URL of the request to the right template file.
  2. Once Shopify has identified the template file to use, it reads the 1st line of the file to know which layout file (still level 1 of the cascade) to use with this template. This is handled thanks to the Liquid tag {% layout %}, which must always be at the very top (1st line) of the template file. If there is no {% layout %} tag, Shopify uses, by default, the layout file named theme.liquid.
  3. Shopify continues parsing the same template file and looks for what sections to display within the template. If there is a Liquid tag {% section %} at one point, Shopify fetches the correct section file (level 2 of the cascade).
  4. Shopify reads the section file that was indicated in the template file. If there is a {% render %} Liquid tag, Shopify fetches the right snippet file (level 3 of the cascade).
  5. Finally, in a snippet file, if Shopify reads an asset_url or asset_img_url Liquid filter, it fetches the appropriate asset file (level 4 of the cascade).

In fact, the cascading system used by Shopify is even more flexible than what we have just described. Any file from a lower level of the cascade can be directly referenced (or included) in a file from a higher level of the cascade. In other words:

  • The Liquid filters asset_url and asset_img_url, used to reference an asset file (level 4 of the cascade), can be used in any file from a higher directory (level 1 to 3). So, the asset_url or asset_img_url Liquid filters can appear directly in a template file, a layout file, a section file, or a snippet file.
  • Similarly, the Liquid tag {% render %}, used to reference a snippet file (level 3 of the cascade), can appear in any file that belongs to a higher directory (level 1 or 2).
  • The same goes for the Liquid tag {% section %}, used to reference a section file (level 2 of the cascade). It can appear in any file that belongs to a higher directory (level 1 of the cascade).
  • Last, the level 1 of the cascade has 2 directories that have a special relationship: they reference each other. A template file references a layout file with the Liquid tag{% layout %}. Reciprocally, a layout file references a template file with a special generic Liquid tag, {{ content_for_layout }}. We will come back to this tag later.

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