Cross-Platform Sass and Compass in WordPress

I find it particularly interesting when other developers share their workflow tips and tricks. It can be very helpful to take a sneak-peak into somebody else's development world and find out what tools they are using to make their own life easier.

Well today I'm going to show you a portion of my own workflow - specifically how to use Sass and Compass when developing a WordPress theme. Instead of simply explaining the configuration and tools needed, I thought it would be better to start from scratch and show you exactly what's needed to get going when developing a WordPress theme that uses Sass and Compass.

I hope this article sounds interesting to you and I'm looking forward to sharing a small part of my workflow with you - I encourage you to do the same.

What You'll Need

After much experimentation, this is the best tool for cross-platform Sass and Compass support. This is a menu-bar only app that can compile Sass files into CSS (it also has live-reload). It is not free, but at $10.00 I've found it more than worthwhile.


In the interest of providing a solution for all readers, regardless of platform, this tutorial will provide configuration for the app mentioned above. There are of course other alternatives, but be aware that things may need slightly different configuration than what you see here.

  • Mac alternative - Codekit
  • Windows alternative - I've not come across a decent Windows GUI alternative other than the app we'll be using in this tutorial. If you know of one, please feel free to share in the comments below.

1. Start With a Theme

The _s theme is a design-less theme perfectly suited for developers. As stated on their website "I'm a theme meant for hacking so don't use me as a Parent Theme." - Sounds perfect for us. Head along to their website, _s theme, and use the 'Generate' command on their homepage to download a custom build. You could simply download the theme directly from GitHub, but then you'd have to manually search for all instances of _s within the theme and replace them with your own prefix. Using 'Generate' does that part for you automatically.

Once you have your custom build downloaded, unzip the theme directory into wp-content/themes. For this tutorial I used the generator to create the theme wp-tuts and the directory structure should now look like this:


You can now go ahead and activate the theme from the Admin Panel.

2. Configuration for Sass and Compass

In the theme's root directory, we'll have a folder called sass. This is where we'll put all of our .scss files. will then watch that directory and compile everything into the single style.css file that lives in the root of the theme.

  1. In the root of the theme, create a folder called sass.
  2. Also in the root, create a file called config.rb

These are the settings that will work well with WordPress:

Ok, we have our sass folder and our config.rb both sitting in the root of our theme. We are now ready to rip apart the theme's CSS file and create individual files that will be easier to build upon / maintain in the future.

3. Convert the Theme's CSS to Sass

One of the advantages to using any CSS preprocessor is the ability to split our CSS into many small files. This helps our workflow tremendously as we can organize our code into related chunks that are easier to maintain and work with. So instead of having everything crammed into one giant CSS file, we can have a separate file that is only for resets. Then we could also have a separate file that only handles the menu, one file for media, etc. etc. We can have as many .scss files as we like, and after compilation they will all be compressed down into a single style.css.

If you look at the style.css file that comes shipped with the theme we downloaded, you'll see that the author has put comments to separate the content into sections like this:

We'll use those comments as a guide for breaking up this stylesheet into separate .scss files.

Within the sass directory, create a file called style.scss - This is the file that we'll use to import all of the other files. Also, this is the only scss file that will NOT be prefixed with an underscore ("_"). This tells our compiler that this file should be converted into an actual CSS file.

Now run through the style.css file and for each commented section, create a new file in the sass folder that is prefixed with an underscore and has the file extension .scss. Copy the contents of that section into the newly created file.

For example, where you see this in the style.css, you would create a file called _navigation.scss and put it within the sass folder:

After running through the entire stylesheet, your sass directory should now look like this. (notice that style.scss is the only file that is not prefixed with an underscore, everything else is considered to be a partial, and will not be compiled into a separate CSS file.)


Now that we've put all the CSS into separate SCSS files, we now need to import those into the style.scss file and also add the theme information.

Ensure these files are imported in the same order that the CSS appeared in the original document. You can see that we start with reset and add the rest in the correct order. You still have to think about the order in which rules are defined in the final CSS!

Important: Also note that exclamation mark (!) on the first line. This tells the compiler not to strip out this important comment. We need to do this because earlier we set the option output_style = :compressed (in the config.rb file). This means that all white-space and comments will be removed from the compiled version. This is a great thing and you certainly want that to happen - but not here! If this comment was removed by the compiler then WordPress would not recognize this theme.

4. Compiling Into CSS

We've done all the manual work, now it's time to bring the automation into play. Go ahead and delete the style.css file from the root of the theme as we no longer need it. Now, if you have successfully followed all the steps above, then you should be able to open up and choose Watch a Folder. Select your theme's root directory (in our case, it's the wp-tuts folder inside of wp-content/themes)

  1. Open
  2. Select Watch a Folder
  3. Select your theme's root directory

After a very short delay, you should see a new style.css file that has been generated. Open it, and you should see a minified version. This is an indication that everything worked as expected.

5. Using Compass

At this point, we've converted the theme's base CSS into small, manageable chunks of code and now we'll look at using Compass with our project.

Compass is a framework that provides a lot of powerful features to make your life easier when crafting CSS. Because we're using, we can bring in the functionality provided by Compass by simply importing the required module in our style.scss file. For example, if you want the CSS3 modules of Compass, just do this:

That's really it, now you can head over to the Compass website and when you're ready to use any of its features in your project, you'll know exactly how to do it.

You're Ready!

You now have all you need to start using Sass and Compass when building themes in WordPress. Next, we'll take a look at a couple of very simple examples of how to use them and whilst this tutorial is not an introduction to Sass and Compass, the examples below should help beginners further recognize the benefits of using a CSS pre-processor.

6. Examples


As we are now leveraging the power of a pre-processor, we can be more efficient when writing CSS and avoid repeating ourselves. One of the things I have on every single WordPress project is a _vars.scss file where I would keep anything that is project specific in variables. That way, I can refer to the variable names throughout many files, and should I need to change something, I would only have to do it in one place.

To use them across your entire collection of .scss files, just @import it like any other file into style.scss, but just make sure it's the first one, or just after reset would be ok too. Once you have imported it, use the variables like this:


Often, many people will only use Compass for its vendor-prefixing abilities. I fall into that category myself and here's a small example to show why:


I hope this tutorial has been helpful in showing a simple but effective workflow when using Sass and Compass within WordPress. The two examples I gave at the end are the absolute basics of using Sass and Compass and you should look into both separately to make full use of them.

Saying that, you'll still be improving your workflow a great deal with what you've learned here. By using these tools to split up CSS into small files, using variables to reduce repetition, and removing the need to type vendor prefixes - you're on your way to better development workflow.



Related Articles