Custom CSS Best Practices: Maintaining Clean and Organized Code

If you’re building a custom Squarespace website, you’ll surely be adding Custom CSS. In this article, I’m going to go over some best practices for maintaining clean and organized code in your custom CSS area.

In my previous article, I talked about the specific syntax behind adding comments to your code and where it can be used in Squarespace. In this article, I’m going to focus more on the best practices for adding comments to your code.

#1: Format your Code

A CSS rule contains two components, 1) a target and 2) the properties that you’re changing, contained in a property:value pair.

target { property: value; }

If you’re changing multiple properties, you can string them right next to each other as long as each pair is separated with a semi-colon.

target { property: value; property: value; property: value; }

Properties strung next to each other like that can be very hard to read though. So add a line break after each semi-color to set each property onto it’s own line:

target { 
  property: value;
  property2: value;
  property3: value;
}

Code that looks like this, where the target is at the top, with each property indented on it’s own line underneath, is called “formatted”. A quick trick to get the indents how you like is to highlight your code and hit SHIFT + TAB

#2: Add Your Own Comments

Oftentimes, code that we paste on to our website is from somewhere else, like Christy Price, Ghost Plugins, and of course, this website.

Sometimes there are already comments in the code, sometimes not, but either way, make it your own by adding more comments! When adding comments in your code, think about your future self. Your current self already knows which block you’re targeting, but your future self won’t. Add comments to help future you remember what the code does, what page it applies too, and where it came from.

Commenting doesn’t slow down your website or hurt SEO, so err on the side of adding more comments than less.

#3: Use a Common Structure

Commenting in your code is meant to save “future you” the trouble of understanding what “past you” was thinking, so help her out! Add in the 3 components of a comment.

Target - Where the code is being applied on your site
Function - What the code does
Reference -Who wrote the code (if not you), add a URL if you want

Here is the general structure of comments that I add:

/**
 * [Target]
 * [Function]
 * [Reference]
 */

You’ll notice I’ll also like to add an additional * on each line. This isn’t necessary when using multi-line comments, but it’s helpful to keep all of the text formatted the same and aligned vertically.

And here is an example of some code in my Custom CSS area:

/**
 * On the About Page
 * Pulls Video Full Width
 * From Will-Myers.com
 */
#block-yui_3_17_2_1_1650403250215_117772 {
  padding: 17px 0px;
  width: 100vw;
  position: relative;
  left: 50%;
  right: 50%;
  margin-left: -50vw;
  margin-right: -50vw;

  .sqs-block-content{
    max-width:1250px;
    margin:auto;
  }
}

#4: Group Code Together

Some websites that I’ve worked on had over 2000 lines of custom CSS. With that much code in the Custom CSS area, it becomes really difficult to change or update your code—even when it is really well commented.

I’ve found that it’s helpful for me to have the same organizational structure for my code in the Custom CSS area. I organize my code from least specific at the top to most specific at the bottom.

At the top of my CSS, I’ll have my global CSS, like CSS Custom Properties, custom fonts, button styles, etc. Anything that’s going to be applied basically to every page.

Then I’ll have my component-specific CSS. This would be like styles to my Summary Blocks or Accordion Blocks.

Finally, I’ll have my page-specific and block-specific code, targeting just a single or a few specific elements.

This isn’t a perfect solution but it does save me some time when scrolling through the 1000+ lines of code. I’d love to hear solutions that you use to organize your code, share them in the comments below.