Compass Compiling and WordPress Themes

If you’re a WordPress theme builder and a Sass/Compass user, first, yay you are awesome! Second, there is this little issue that will probably crop up for you regarding compile locations, so let’s solve it now.

There are two very important things regarding CSS and WordPress themes:

1. There absolutely must be a “style.css” file in the theme folder.
2. That file absolutely must start with a comment block like this:

/*
Theme Name: Twenty Ten
Theme URI: http://wordpress.org/
Description: The 2010 default theme for WordPress.
Author: wordpressdotorg
Author URI: http://wordpress.org/
Version: 1.0
Tags: black, blue, white, two-columns, fixed-width, custom-header, custom-background, threaded-comments, sticky-post, translation-ready, microformats, rtl-language-support, editor-style, custom-menu (optional)

License:
License URI:

General comments (optional).
*/

If the file isn’t there or the comment block is missing, WordPress won’t even recognize the theme.

If you’re working with Sass/Compass and you have a really simple stylesheet for your theme, perhaps it’s all in one file and you just have a directory like this:

/wp-content
  /themes
    /your-theme
       config.rb
       index.php 
       style.scss
       style.css

Your config.rb file (for Compass) is super standard, like this:

http_path = "/"
css_dir = ".."
sass_dir = ".."
images_dir = "images"
javascripts_dir = "js"

output_style = :compressed
environment = :development

That’s fine. You’re all set. All you need to do is make sure you use a “!” in the comments at the top of the style.scss file so that, even when the compiling/compressing happens, the comment remains:

/*!
Theme Name: Your Theme

etc...
*/

The Problem

Many of us don’t have a setup that simple. I like to work in small chunks with my Sass, not jam everything into one file. I much prefer to have css and scss folders in my theme. Like:

/wp-content
  /themes
    /your-theme
       /css
          site-sub-section.css
       /scss
          _grids.scss
          _normalize.scss
          _typography.scss
          site-sub-section.scss
       config.rb
       index.php 
       style.scss
       style.css

The problem is there is no Compass configuration that will allow these compile paths.

The Solution

1. Set your config to the even-more-standard of compiling the scss folder into the css folder.
2. Move the style.scss folder into the scss folder.
3. Upon successful compiliation of style.scss into style.css, automatically move style.css out to the root folder.

New config.rb:

http_path = "/"
css_dir = "css"
sass_dir = "scss"
images_dir = "images"
javascripts_dir = "js"

output_style = :compressed
environment = :development

Apparently any code you put in config.rb runs every compilation, so to accomplish #3 we can write Ruby code to execute when certain events happen. In our case, when a stylesheet is saved (Compass is done compiling it) we check if that file is named “style.css” and if it is, move it up a directory. The puts statement is just so you can watch it work from the command line if you want.

require 'fileutils'
on_stylesheet_saved do |file|
  if File.exists?(file) && File.basename(file) == "style.css"
    puts "Moving: #{file}"
    FileUtils.mv(file, File.dirname(file) + "/../" + File.basename(file))
  end
end

Thanks to Christopher Eppstein for showing me how this works.