If we look at the directory structure of a template, we will usually find the following 6 directories.

Layout Directory

The layout directory contains a file named theme.liquid (and not differently) which contains the aforementioned master template. All files that contain Liquid placeholders or commands need to have a .liquid extension (this is valid for all files of a theme). While you still need the original file extension for asset files (e.g. .css files), they need to be removed for all Liquid HTML files. This is the only file in that directory.

The theme.liquid needs to contain two special markers named {{ content_for_header }}, which must be placed within the header and {{ content_for_layout }}, which must be placed in the body. Some analytics code, etc. need to be inserted in the header for a specific shop. Further, the actual page content is at the position of the second placeholder.

Templates Directory

This directory contains all templates for the various pages of the shop. They will be inserted in the master template (at a defined position). In order to provide a full set of pages, there need to be the following templates/files:

Template nameDescription
404.liquidPage not found
article.liquidBlog article
blog.liquidBlog summary page
cart.liquidThe cart page showing the items in the cart
collection.liquidLists all products of a given category/collection
faq.liquidShows frequently asked questions
index.liquidThis is the start page of the shop A contact page
page.liquidAll kinds of HTML content can be displayed here, a kind of 'blank' page
product.liquidShows details of a product
search.liquidShows search results (and perhaps a search form)

Snippets Directory

The snippet directory contains snippets of HTML code (usually containing Liquid code, but it would also work with plain HTML data). This can be inserted in any of the templates (or even several times on the same page). By doing this, code duplication can be prevented (one of the largest origin of programming mistakes). If you think about using copy & paste for reusing a small part of HTML code, it will be best to create a snippet for it! The files in there can be of any name, just the extension need to be .liquid. There is a Liquid command for importing these snippets at any place in any template.

Assets Directory

Basically, no web page can live without the assets, which are all the files which are not HTML and belong to the web pages. All these must reside in this directory, one subdirectory level within this directory is permitted. Of course also assets (e.g. CSS files) can contain Liquid code - such files must be marked by adding the file extension '.liquid' to them (e.g. main.css.liquid). Beside CSS files also SCSS files are supported and are automatically compiled when needed.

Config Directory

This directory usually contains two files called settings.html and settings_data.json. The settings.html file defines an HTML page which acts as a kind of settings editor web page. It contains a form with various input fields, which are finally stored in a settings object and provided on building the template. This possibility of easy configuration allows users to configure the shop template in their fashion (e.g. with their corporate identity background color, etc). The input fields should give default values (where appropriate). The file settings_data.json contains JSON data, which is constructed the following way: In the top level, there are two nodes 'current' and 'presets'. While 'presets' is an array and could contain any number of presets (with the preset name as node name, the underlying object is always a complete set of settings), the 'current' node contains the default settings. The names of each setting should match those in the HTML form, the values are these specified in the input fields. Please make sure that bool values (e.g. checkboxes) are stored as bool (true) and not as a string("true"). The currently used settings of a web shop can be downloaded from the admin interface, but it will not include the enclosing 'current' or 'preset' JSON tags.

The settings, which are defined by the settings.html and settings_data.json will be stored in a Liquid variable called 'settings'. Imagine you have a setting which is called 'text_color', then you would access this variable e.g. by writing <div style="color: {{ settings.text_color }};">Demo Text</div>. You will find more information in the object type section.

The structure of the settings.html file is as follows:

You mustn't specify any HEAD, BODY or FORM tags for the HTML code, all of it will be provided by the web server. For better separation of the options, you should use FIELDSET/LEGEND and LABEL (for each input) tags to structure your settings page. Most probably the best option is to layout each FIELDSET into a table with settings names in the left column and the appropriate input field on the right. You can't use custom CSS styles and also no javascript on that page, only plain, XML compliant HTML code.

The names of input fields are the names with which the settings can be accessed later on. For example if you have this input field (with specifying a default value – where appropriate):

<input type="text" name="tagline" value="Best shop ever" />

Then you are able to access this setting using

{{ settings.tagline }}

which will be replaced in any file (including .CSS and .js files) with a .liquid extension.


Read more

Read more about input types

Languages Directory

In this folder you are able to store any number of .resx files which can be used for easy translation in any language. Usually you would start with an English .resx file (thus it will have an .en.resx extension). All translations will have the same name as the original file, but the used language noted in the extension (e.g.  .de.resx). The file name doesn't matter, all files in that directory will be loaded.

There are plenty of tools available to create and edit .resx files. These files contain tuples of strings, one identifier and one text. The identifier should only use standard letters and no spaces, the text itself can contain any characters and even HTML code (but which would be not so nice to edit). Please make sure that all identifiers of the translation files are unique, so that no identifier will be overwritten.

In the templates you can use the identifier in combination with 'translation' as a placeholder to replace it with the given text e.g.  {{ translation.cart }} will replace with 'cart' (English) or 'Einkaufswagen' (German), etc. (as long as these languages are defined in the appropriate .resx files).