Getting Started with the Squarespace Developer Platform


1. Sign up for Squarespace

When starting your adventure into the Developer Platform, you'll (obviously) first need a Squarespace site.  You can choose to start with one of the consumer Squarespace templates (and you'll have full access to the template code), or you can start with the Base template, which is a bare-bones site that allows you to start from scratch.

Start with a Squarespace Template

Start with the Base Template

Note: Developer sites exist as an unlimited free trial. This means your site will not expire until you are completely ready to launch. So don't worry about paying immediately when you sign up for the trial.

2. Register as a Developer

After you sign up for your Squarespace site, you'll need to register as a developer to gain access to the template code.  Take a look at the left hand side of your site - this is the Squarespace 7 UI and where all the relevant information resides.

Click the default gravatar image above your name in the left corner:

Click 'edit profile' on the dialogue box that appears:

Click the 'Developer' tab and fill out the registration form:

Sweet! Now you're a Developer. Congrats, noob.  Let's get you to post-noob status.


3. Flip on the Developer Toggle

Now that you're registered as a Developer on Squarespace, you'll have access to Developer Mode, which will allow you to Git clone your template repository, or upload/download files via SFTP (more on both later).

Note: If you did not register as a Developer, you will not have access to the Developer Toggle (you'll see a blank section).  Refer to step 2 and don't mess up this time.

Navigate to Settings > Advanced > Developer Mode:

 Flip the toggle on!

Flip the toggle on!

Note: You'll see a warning appear when you flip the toggle on.  It's basically saying "you're responsible for your own code" - just be aware that if you create syntax errors when writing code and your site breaks, it's on you to figure out what went wrong.  Although it's not impossible that it's an issue with the Squarespace system, try to determine that for yourself before sending the customer care team an email.

4. Download your Template Files

Alright, here's where you'll see a whole bunch of information that will allow you to connect to your site.  I'll separate this out into SFTP and Git information.  First, here's what the Connectivity Details section looks like:

connectivity.png

SFTP Connection Details:

SFTP Hostname: dev.squarespace.com
SFTP Port: 2030
Username: The email address you used to sign up for Squarespace
Password: Password you chose when signing up for Squarespace

Use the above information in your SFTP client of choice to upload/download template files directly from/to the server.

Git Details:

git clone https://[your-site-url].squarespace.com/template.git

Type the above into your Terminal application to clone your Squarespace template repository.

Note: If you're new to both Git and SFTP, refer to this tutorial which will get you up and running on both

Once you've either cloned your repository or downloaded the template files via SFTP, you should see a file structure that looks like this:

Note: You might see a different file structure depending on the template you started with.  If you started with Base Template, you'll see the above architecture.  If you started with a Squarespace consumer template, you might see varied files inside each folder.

I go into greater detail of each file and folder in this tutorial.  But for now, let's tackle the absolute necessities to get up and running.

  • /assets - Folder where your template assets (static images, font families, etc) live.
  • /blocks - Folder where partials live.  Partials are reusable bits of code (such as a Navigation section).
  • /collections - Folder where 'collection types' live. Collections are Pages, so think the markup for your Blog page, or your Gallery page, or your Products page.
  • /pages - Not to be confused with collections, the /pages folder is for Static page types that can't be changed in the content editor.  Basically, a non-CMS HTML page.
  • /scripts - Where your JavaScript files live
  • /styles - Where your LESS and CSS files live
  • site.region - Your markup - formatted in HTML and JSONT (like a standard .html file).  You can write and combine multiple region files to create dynamic layouts and pages
  • template.conf - Formatted in JSON, this file puts each individual file together into a cohesive site

5. Make Some Changes

To see how this all plays out, create a new file called styles.less in your /styles folder.  Let's add some CSS to change the body background color.  Try this:

body {
  background-color: green;
}

Save that file.  Now, open up your template.conf file and add "styles.less" to the "stylesheets" key's array.  Like this:

"stylesheets" : [ "base.less", "styles.less" ],
Note: You do not need to keep base.less if you don't want to use the basic styles.  Simply remove it from the array.  Always be sure to comma separate any stylesheets you add into the array, and wrap them in quotes.

Your entire template.conf file should now look like this:

{
  "name" : "Base Template",
  "author" : "Squarespace",
  
  "layouts" : {
    "default" : {
      "name" : "Default",
      "regions" : [ "site" ]
    }
  },
  
  "navigations" : [ {
      "title" : "Main Navigation",
      "name" : "mainNav"
  } ],

  "stylesheets" : [ "base.less", "styles.less" ],

  "systemCollections" : [ "products" ]
}

Now save this file.  SFTP or Git add, commit and push your changes (style.less and template.conf) to your site.  Navigate to your site in your browser or refresh the page, and you should now see that your Body's background color is green.  Hooray!

Be sure to check out the Developer Platform Documentation for additional information.  Now go forth and break stuff.