How URLs Map to Shopify Templates

One of the (many) features I love about working with Shopify Themes is the simple folder structure. Each store can be powered by a single layout file and a handful of templates meaning you can achieve a lot with a little — power in simplicity.

However if you are new to Shopify Themes, you may not know exactly when each template gets rendered, or be aware that the same template gets used in various places around the store.

We've already looked at how to use both alternate layout and template files, therefore in this article we'll turn our focus to understanding under what conditions each template is rendered in a store.

While we're on the topic of URLs, learn more about what a canonical URL is, and why they're so important.

URL template mapping

Internally, Shopify has its own routing table which determines which template is displayed based on the URL requested by the user. If you have ever used one of the popular development frameworks, you might be familiar with the concept of URL routing. Put simply it's a way of determining which template to send to the browser based on the requested URL.

I mentioned earlier that there are only a handful of templates required to power a store. Each of these templates serves one or more URL — in other words, we are able to utilise the same templates for multiple URLs. From a design perspective, this enables us to reduce our overhead when building a new store.

You might also like: Using Metafields in Your Shopify Theme

URLs to templates

Here's an overview of which template is rendered as determined by the URL:

/thisisntarealurl → 404.liquid
 /blogs/{blog-name}/{article-id-handle} → article.liquid
 /blogs/{blog-name} → blog.liquid
 /cart → cart.liquid
 /collections → list-collections.liquid
 /collections/{collection-handle} → collection.liquid
 /collections/{collection-handle}/{tag} → collection.liquid
 / → index.liquid
 /pages/{page-handle} → page.liquid
 /products → list-collections.liquid
 /products/{product-handle} → product.liquid
 /search?q={search-term} → search.liquid

Password protected

You might have noticed that the password.liquid template is not included in the list. This template is only seen if you choose to password protect your storefront and as such will override all other URLs.

If your store is password protected and you do not have a password.liquid template in your theme, Shopify will render it's default password login page instead.

Alternate templates

It's also worth remembering that the above routing table can be affected by alternate templates — something we have covered in a previous tutorial.

URL parameters

As you will see above, a number of the routes have elements of the URL path wrapped in { }. I have included this to denote a variable which will have an impact on the data loaded into a template.

For example, if we take the /collections/{collection-handle} URL pattern a different set of data will be loaded into the template and sent to the browser if we requested /collections/bikes compared to /collections/cars.

You will also notice that a number of different URL patterns share the same template file, e.g /products and /collections will both render the list-collections.liquid template. Likewise /collections/, /collections/{collection-handle}/ and /collections/{collection-handle}/{tag} all make use of collection.liquid.

Final note

If you are ever unsure which template is being rendered, there's a really simple way to check.

All you need to do is add {{ template }} to your theme.liquid file and start browsing your store. This global Shopify variable will output the currently rendered template minus the .liquid extension. It's a neat way to be doubly sure your templates are working as expected.

Here's a handy snippet that you can use in your own theme development with the output shown in the screenshot below:

<p style="display: inline-block; background: yellow; border: 1px solid #CCC; padding: 1em; font-weight: 700;">Current template: {{ template }}.liquid</p>

Want to learn more about building with Shopify? Check out our full list of Shopify tutorials.

You might also like: How to Optimize Themes for Performance