Article  |  Development

How We Built Our New Website On Squarespace

Reading time: ~ 7 minutes

How We Built Our New Website On Squarespace

The endeavor to remake began months before I joined the project team in September 2015. By the time I started, the team had already created a bold new site design, installed a robust framework and everything was running on the shiny, Squarespace-powered CMS. I want to share our experiences working with this new (to us) platform and discuss the pros and cons we encountered along the way.

Why Squarespace?

Squarespace offers a number of benefits, especially for the average person who’s in need of a website that’s as easy on the eyes as it is to create. Squarespace has built a platform that’s accessible to pretty much anyone who can use a modern browser. A person can very quickly build a functional, awesome-looking website in no time at all with only a small learning curve. No advanced web building skills needed. However, for experienced web developers who work almost exclusively with high-level, open source technologies, Squarespace may present a number of challenges from the get-go.

That’s not to say it was a bad choice for us. One primary goal for the new Planet Argon site was to build something that could be updated by anyone on our team, developer or not. Squarespace helped us achieve this goal with a beautiful, intuitive interface that’s easy to use and that makes content management less of a chore. An additional benefit to the front-end team was not having to rely on much support from the back-end team. We also wanted to try something new and learn a platform that could work for a future client.

If you’re a developer thinking about using Squarespace for your next project, consider some of the steps we took to make this task job a little easier. Any criticisms presented here are intended to help would-be Squarespace developers on their journey, as they seek to understand how this relatively new CMS works.

Once we dove into the real grit of development, the team raised several important questions. How do we get around Squarespace’s limitations for local development? What’s the best way to collaborate via Git and work on new features with each other? How much customization and control can we extract from such a tightly controlled dev environment? Let’s walk through it – I’ll try not to get overly technical!

Development Platform

It’s a good idea to start by getting familiar with the Squarespace Developer Platform. Checkout the Development Docs to learn about performing an initial setup in Developer Mode and to get a feel for their templating system, their use of JSON and more. If you’re working with a larger team of devs like ours, you’ll probably want to read through their section about using Git. Repositories are controlled by Squarespace and anything that’s pushed to it goes live. For this reason, we resorted to using a second repository hosted on our own GitHub account for local development and so that we could keep control of our own code.

Locals Only

We solved the issue of local development, or a lack thereof, with a handy node.js dev server, created by Brandon Kitajchuk. It’s easy to install and absolutely essential for building your Squarespace site locally. With this server running, you can write all your template files, styles and scripts without having to constantly push them up to the production server to view them “live.”

As much as we relied heavily on the Node Squarespace Server, we found it falling a little short because of the death grip Squarespace imposes on its platform. One major drawback is that the local server doesn’t work offline because it’s constantly pulling data from the production server. In that regard, it doesn’t feel like a truly local environment, like you would have when using a tool like MAMP for WordPress development. Keep in mind that this tool is a work in progress. The author clearly states this on his repository, reminding us that it’s a “step in the right direction for open-source Squarespace development.” We couldn’t agree more.

Sass Up Your Squarespace

Squarespace supports Less natively so if you’re going to style with Sass, like we did, you can use something like Compass or Grunt to compile your code into a CSS file that Squarespace can use. The one inconvenient aspect of using Sass in this way was having to continuously push our work into two different repositories.

Earlier I mentioned our use of two seperate repositories because of Squarespace’s control over the one you receive when Development Mode is activated. One repo is hosted on our own GitHub account for the Sass files, pushing up the outermost project that contains all the site and template files. The other is the actual Squarespace live production repo for the template folder which is where the compiled site.css file lives.

This process felt cumbersome to us but we simply grew accustomed to the unusual workflow. Prepare yourself to deal with conflicts from time to time, when someone else on the team pushes changes to that compiled css file.

Custom Squarespace Build-Out

Now for the technical half of this blog post: let’s go over how we went about building our Squarespace template.

– Collections & Partials

To build our site structure, we followed a development path that made use of Squarespace’s powerful content collections and partials system. Squarespace collections allow you to assemble pages which display a collection of related posts or items, easily created by the CMS user. We set up collections for team members, our work, testimonials and skills.

Collection items can be displayed on collection pages using the .list file extension but they can also be used anywhere on your site with the Custom Query Tag in a template file.

<squarespace:query collection="work" limit="6" featured="true">

Our testimonials, for example, show up in several different places using this technique. There are limits to the number of items that can be called in but there are also a few filter options for this query. You can display featured items and render items by tags and/or categories.

This is a good time to introduce the .block partial and how we made use of this helpful feature.

<squarespace:query collection="skills" category="Deployment">
 {@|apply featured-skills.block}

When you apply the partial like so, you can call in that chunk of code, whatever is in the .block file, and reuse it throughout your site. This worked great for our skills section, allowing us to display filtered content at various points throughout the page. Instead of writing lengthy markup, we can use these partials to quickly call in the content we need. This elegant feature will have most developers with CMS-building experience feeling right at home.

– Custom Post Types

Squarespace allows you to add Custom Post Types to a collection, which allows you to create custom fields that appear on a particular collection’s item in the CMS admin. The content added into these fields can then be displayed however you choose. Although the content types available for this feature are limited, this additional layer of customization is very useful. We used Custom Post Types almost across the board, but especially with our featured work section.

You must first set your customTypes in the template.conf file.

"customTypes": [
       "title": "Work Info",
       "name": "work-info",
       "base": "text",
       "fields": [
           "name": "url",
           "type": "text",
           "title": "Full URL"
           "name": "clientName",
           "type": "text",
           "title": "Client Name"
           "name": "tagLine",
           "type": "text",
           "title": "Tag Line"
           "name": "conclusion",
           "type": "text",
           "title": "Conclusion Summary"
           "name": "testimonialImage",
           "type": "image",
           "title": "Testimonial Image"
           "name": "testimonial",
           "type": "text",
           "title": "Testimonial"
           "name": "testimonialSource",
           "type": "text",
           "title": "Testimonial Source"
           "name": "testimonialSourceTitle",
           "type": "text",
           "title": "Testimonial Source Title"
           "name": "testimonialWorkVideo",
           "type": "text",
           "title": "Testimonial Work Video Embed Code"

Once you set up your fields in the template.conf file, you can reference these custom post types throughout the markup of your template files, in place of actual content.

<h2 class="margin-0">{customContent.tagLine}</h2>
<h3 class="uppercase">{customContent.clientName}</h3>

Check the Squarespace Developer Docs for more detailed information about these features. There are a few other important elements such as the navigation tag, layouts and regions that we recommend studying up on as well. I can’t help but point out that there is a real void of knowledge out there when it comes to Squarespace development. Many of the questions on their support pages have gone unanswered for years and relevant topics on StackOverflow are sparse. At times, it felt a bit like the Wild West.

Don’t let this discourage you though. Much like the many pre-made templates Squarespace offers its non-dev customers, the system rewards simplicity. Keep your site’s design and structure clean and don’t overthink or complicate your content design. Find an organizational pattern that works for you and stick to it. You’ll be okay!

Content Creation

Squarespace users have several options for creating content with their CMS by choosing from one of the many provided blocks. There are blocks for typographical elements, images, videos, galleries and more. We found that, when creating a site as customized as ours, most of these blocks go unused because of the aforementioned death grip. Squarespace does not allow developers to crack them open for html customization.

This doesn’t mean you’re totally out of luck. You can modify these block page elements if you target their CSS style properties. For example, it would be possible to change the font size on the default headings or add space around certain elements. You can also add any custom content you like with the code block but this is more of a hack and probably not a viable option for your client, especially if they’re not okay with writing front-end code on a regular basis.

Admittedly, we use the code block to create the majority of our one-off pages within the CMS. Using this special block, we write html using elements from Bootstrap and all the other style classes we created to build a page. You can also use the code block to insert third party embed scripts from services like Hubspot, Wufoo, Wistia, etc.

Final Thoughts

During our internal retrospective for this project, we found ourselves having more to say about Squarespace’s shortcomings. Some people on the team have even proposed moving to a new platform altogether. I think there’s still room for improvement on what we built for this system.
If we had to start over, we might try a different approach. Ours was to shoehorn in a pre-made design using a workflow that makes more sense for Rails-based projects.

Perhaps it would have been better to start by embracing Squarespace a little more and build with the blocks and elements they provide, then continue on to explore our customization options. It’s possible we could have saved ourselves time and frustration by using Less instead of Sass. Luckily, this project is still open for improvements so we’ll continue to discover and employ better tools and methods.

Can we recommend Squarespace to you, fellow developer? That depends. If you and your client need lots of options for customization and want support from a large community of knowledgeable users and developers, Squarespace may not the best choice. If you can get away without having to create so many modifications and you really like the Squarespace UI, you can easily hand your client a beautiful product that’s ridiculously simple to maintain.

Have a project that needs help?