Each Squarespace Template is made up of a series of predefined folders and files structured very similarly to a static website. This section will explain the purpose of each file and how they are organized into folders.
Languages and Filetypes
JSON Template Files
Squarespace template files are written in JSON Template, also known as JSON-T. It is an easy to use, easy to read, minimalist template language. JSON-T extends HTML, so you can open these files as HTML files in your editor. JSON-T files have different extensions depending on the type of file, for example .list, .item, and .region. See the section below on Template Directories for a discussion of the different file types.
Template LESS files (.less) are processed through the LESS preprocessor. LESS extends CSS with dynamic behavior such as variables, mixins, operations and functions. (Note: we also run .css files through the LESS preprocessor in order to parse special styles for our Style Editor.)
Template File Structure
At the very minimum, your template needs a .region file and a template.conf. The site.region is typically the main template file for your website. It's your website's index.html, or if you're familiar with Wordpress, index.php. The template.conf is the main configuration file for your site. It tells Squarespace how the rest of your website is configured.
Squarespace template files are organized using the following folder (or directory) structure at the root of your site:
- assets design assets — example: images, fonts and icons
- blocks block files — navigation.block
- collections collection files — [collection].list, [collection].item, [collection].conf
- pages static page files — [static].page, [static].page.conf
- styles stylesheet files — styles.css, styles.less
- [root] sitewide files — site.region, template.conf
Each template is made up of a collection of template files. Template files fall into three categories: site-wide files, collection-specific files, and block-specific files. Templates may or may not include all of the folders listed above, and missing folders can be added using SFTP or Git.
A deeper look at the (pre-defined) folders that are used to structure the files in every Squarespace template.
This folder is a general purpose storage folder for static template assets: Images, Icons, Web Fonts, etc. There is a 10MB file size limit on each individual file inside this directory. After uploading, assets are available at a static URL:
The contents of this directory are also cached by the Squarespace CDN.
In this folder, you will find the templates and configuration files for Squarespace block files. Block files as pertaining to templates let you create reusable partials or 'includes'. These are primarily used to create and configure navigations.
- .block - Block template files. (JSON Template)
- .block.conf - Block template configuration settings. (JSON)
See Blocks for more details.
In this folder you can define the presentation for the various kinds of content in your template. You can have an unlimited number of collection types in each site. Each collection can be configured to support specific post types and can be sorted chronologically (like a blog) or user ordered (like a gallery). Each collection must have a configuration file and at least one
All .list and .item files are written in JSON Template.
- .list - Templates for the list view of a collection. Example: blog.list templates a list of blog posts. This is the default view of every collection. (JSON Template)
- .item - Templates for the individual page view (permalink) of a collection item. Example: blog.item templates a single blog post page. If a .list file is not provided, the .item will become the default template for the collection (redirecting visitors on the first individual item page instead of the item list page). (JSON Template)
- .conf - Contains the configuration settings for a collection. There is one configuration file for each collection. (JSON)
See Collections for more details.
This folder contains static site HTML pages. These are a special type of collection that do not inherently have data of their own. These pages can not be modified within the Squarespace interface by the end user.
- .page - HTML markup for a page. (JSON Template)
- .page.conf - Contains configuration settings for a page. (JSON)
This folder contains the scripts for your website. To include a script in your template, in the <head> area of your template, use:
<squarespace:script data-preserve-html-node="true" src="your-script.js" combo="true"/>
This syntax will ensure that your script is loaded via the proper URL, and Squarespace will automatically attempt to merge multiple scripts into a single download if the combo parameter is set to true.
This folder contains the CSS styles for your website. All Squarespace CSS is processed using less.css syntax. To include CSS files in your template, edit the template.conf and list the files in the order you wish to include them. For example:
"stylesheets" : [ "global.css", "my-site.less", "another-style.less" ]
All stylesheets added to the template.conf in this way will be merged and served as one CSS file automatically. You do not need to add any stylesheet links to the HEAD section of your site.
NOTE: If you add a file named
reset.css to the /styles folder it will automatically be added to the top of the site.css file and it should not be listed in the
stylesheets variable in the
Typically this file is used as the global site wrapper template – containing the site header, footer, and sidebars. Every template must have at least one .region file. Simple templates will have a single .region, more advanced templates will have multiple .region files describing header, body, and footer variants. Regions files live in the root directory of a template.
See Layouts & Regions for more details.
Contains the configuration settings for the template. This is where you can name your template, specify layouts, add navigation sections, specify stylesheets to be rolled up into site.css, and other general site options. Template configuration files must live in the root directory of a template.
See Template Configuration for more details.