Filtering by Category: Basics

Using Git


This post is for those who have never used Git and are afraid of the command line.  By the end of this post, you'll sort of know how to use Git and be only moderately scared of the command line.

What is Git anyways? Git is a version control system.  Let's say you push a bunch of code to your Squarespace site with Git, only to realize you need to revert back to the previous state of the site before the push because you've discovered a bug.  Well, this is what Git is for.  You can easily 'roll back' to the previous version while you figure out what went wrong.

1. Install Git

You can download Git here - if you're on Windows you'll need to take a few extra steps (which are outlined on Git's website).  Going forward, this tutorial assumes you are using a Bash-like Terminal application (this is standard on Mac and Linux machines).  Windows users will need to download a Bash client for the following commands to work.

Once Git is installed, open up your Terminal application (also known as a Command Line Interface, or CLI).  Type in the following:

git --version

This will return the current installed version of Git.  Anything you want to do in the CLI with Git must be preceded with the word 'git.'  So for example:

git --help

or

git add styles/styles.less

Now, let's go over a few useful CLI commands (not specific to Git, but for navigating through folders and filepaths on your computer).

  • ls - short for 'list' - when you type ls and hit enter, a list of files and folders in your current directory will appear.
  • cd [directory-name] - means 'change directory'.  This is how you move inside a folder in the CLI (similar to double clicking a folder if you were doing it the way you normally would on the desktop).  Don't put the actual directory name in square brackets.
  • cd .. - this goes up one level, or back (as if you hit the back button to go back to the previous files and folders).  
  • mkdir [directory-name] - means 'make directory', this creates a new folder at the current file path.
  • pwd - means 'print working directory', which just tells you the current filepath or folder you're in

Okay - that should be enough to move around your computer through the CLI and create files and folders where you need to.  Now let's mix in some Git.


2. Clone your Template Repository

A repository, or repo for short, is just a folder where all your template code and version history lives.  All Squarespace sites are a Git repository by default, which means you can easily clone the repo, make some changes, and push it back to Squarespace.  Ready for your first Git command?

In your Terminal, make a new directory somewhere (remember, mkdir [directory-name] and then move into it (remember, cd [directory-name]). On my own computer, the folder with all my Squarespace sites is in a directory called Squarespace. So here's what that would look like in my CLI:

mkdir Squarespace
cd Squarespace

Now you're inside the Squarespace directory.  Type pwd to be sure of your current path.  Now, type ls in the CLI.  Nothing appears?? That's normal - we just created the directory and there's nothing inside yet.  Let's clone your Squarespace site! Type this:

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

What just happened? You told Git (by starting with 'git') to 'clone' (or download/copy) the repository hosted at https://[your-site-name].squarespace.com/template.git and put it in a new directory called [your-site-name].  Remember to replace [your-site-name] with whatever your Squarespace URL is (and don't put it in square brackets).  

If you now type ls - you should see one new folder in your Squarespace directory, and that's where your Squarespace template repository lives!

Now, let's move into that new directory.  Type cd [your-site-name] and pwd to be sure of where you are.  Then enter ls to see what this repository has to offer.  It should look something like this:

Awesome.  Leave the Terminal app open for now, but let's open the repo in a text editor so we can make some changes.  You can do this through your Finder.  I don't have to explain this part.  Just open the folder in Sublime Text, or Coda, or whatever you have installed.

Once you've opened it, open your /styles folder and the base.less file.  Make any change at all to the CSS.  Change the background-color of the body element, for example.  Then save it.

Go back to to your Terminal app (CLI), and type in the following command:

git add styles/base.less 

What you're doing is telling git to 'add' the base.less file for git to track changes.  Now, you'll tell git to 'commit' the change to the repository, using the following command:

git commit -m "changed something in base.less"

The flag -m followed by the comment in quotes adds a commit message, so that you can remember what this commit was for.

Finally, push the commit to your Squarespace site using this command:

git push

And those are the basic commands you need to know to clone your repo, track changes, and push commits to your Squarespace site via Git and the CLI!

There are some other useful commands as well, such as git pull (and git pull --rebase origin master) - which pulls the latest code from the repository (in case you are working on the site from two different computers).  Be sure to read the Git documentation to know what you can really do with Git, as it's super powerful.

No Comments

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.

No Comments