Grow your CSS skills. Land your dream job.

Compass Compiling and WordPress Themes

Published by Chris Coyier

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.

compile-no
Not gonna happen, apparently. (This is a way simplified WordPress theme directory. Imagine loads more files.)

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.

Comments

  1. How about another way?

    1) Put an empty style.css in your theme folder containing nothing except the regular theme comment/declaration (to ensure WP recognises it as a theme).

    2) DON’T put the style.css in your theme’s header.php

    3) Instead, enqueue the compiled Sass file from your functions.php and the folder of your choosing.

    It’s late and I’m just thinking out loud, so apologise if I’m off base with this idea. Seems like it should work though?

    • So, this should work. One downside is that if you plan to distribute the theme, it could be confusing for somebody who opens style.css and finds a blank stylesheet.

    • Sure that makes sense too. Don’t do like I did at first and put a style.css file that @imports something from the /css/ directory. That’s two requests for no reason, which lead me down this path.

      Also note that then the bloginfo('stylesheet_url'); will return your blank stylesheet. Easily fixable, but it would affect me since I like using that.

    • Permalink to comment#

      @matt: cheers, that’s exactly how I do it too. I even sometimes include a less-compiler, for theme customisation support (so wordpress won’t print inline stylesheets – I’m filtering those).

      @josh: if you’re up to opening styles.css, you can figure out where the real code is too.

    • Luca Rosaldi
      Permalink to comment#

      The method Matt suggested (style.css with only WP comments and @import) is the same I use too, and I think it’s the best way to go.

      I don’t think it’s confusing if you distribute the theme, because when someone opens a CSS file, you can safely assume that he’s a web designer, or at least someone who knows what he’s doing. A good theme developer provides other ways for non-savvy users to change the appearance of the theme, anyway.

      Having .scss files scattered around my theme – that is confusing to me. I’d keep all of my SASS files in the .sass folder, so I know where I can find them.

    • Tobias
      Permalink to comment#

      That is exactly what I would do :).
      @Josh: Just add another comment in your empty style.css that leads to the real stylesheet – which should not be hard to find in any case…

    • Permalink to comment#

      @Josh – true, but it’s brilliant for people like me who create themes just for clients, and for my own side-projects. I’ll definitely be using @Matt’s method instead.

    • Is there a good step by step anywhere to do @matt’s preferred way?

  2. Matt Banks
    Permalink to comment#

    Are you still using CodeKit for compiling everything? I put an scss directory in my theme with all of my partials and a style.scss that @imports everything. Then in my config.rg, I set it up with: css_dir = "/" and sass_dir = "scss". No extra Ruby code needed and it compiles to style.css in the root of the theme.

    • Permalink to comment#

      Matt, this is awesome and very easy to implement, thanks mate! Just updated my site and it works a charm. Changing the css_dir did break a few paths but I have them saved as variables so it wasn’t hard to update them from $image-path: ('../images/'); to $image-path: ('./images/'); for example.

    • Yep! This is exactly how I do it. I think it’s the easiest way to get going. However, this extra ruby code seems interesting enough to try out.

    • Permalink to comment#

      This works great for me! Thanks Matt. On another point if anyone here uses Espresso as their code editor – be careful. I have been tearing my hair out with failed compilation. In the end I tracked it down to inconsistent file encoding caused by Espresso. Hope that helps someone.

  3. Permalink to comment#

    why would you messup the ruby files and PHP files? i would recommend you to use

    https://github.com/roytomeij/sass-for-wordpress/

    or

    http://forge.thethemefoundry.com/

    rather messing around with the files.

    Yoosuf

    • Looks cool, but:

      First, you need to have the Sass and Compass gems installed on your server to use the plugin.

      I’m such a noob I don’t even wanna think about installing Ruby and Gems on my server. Who knows what kind of resources that uses and what extra security stuff I then need to think about.

  4. Matt Banks
    Permalink to comment#

    Meant to put in my first comment, but I have it all setup in my WordPress Starter Theme on Github: https://github.com/mattbanks/WordPress-Starter-Theme

  5. Danilux
    Permalink to comment#

    I also develop the way Matt says, I think simplicity wins, just place an empty style.css on the root of your theme just to please wordpress, and work normally with sass, meaning you write your scss inside your sass folder and you get the compiled css inside css folder, then just enqueue the compiled style.css from the css folder during development and move it to the root when finished, to replace the empty one with the compiled one. I have a lot of scss partials that are imported to the compiled style.css and it works awesome.

  6. Hm, does this solution also work on Windows with Compass.app?

    I was under the impression that with that setup, the .SCSS has to be in a folder called “SASS” and it will always compile into a folder called “stylesheets” — that’s simply where Compass.app will take the input and output, and I haven’t found a way to change that anywhere.

    Not sure if it’s the same on Mac.

    Compass.app doesn’t require any further Ruby configurations, so setting the paths and all is not relevent then, I guess.

    Hence, for those who use Compass.app, they may have to use @import “stylesheets/default.css”; in styles.css and have Compass.app watch the theme/themename folder.

    I could be wrong, though.

  7. ADD: the config.rb can be edited so that it will move a file from /stylesheets to the theme root. Just not sure which config.rb to use (I have dozens in my C:/Ruby folder). Come to think of it, editing the proper config.rb file will probably enable me to set the paths so that I’m not bound to using the SASS and STYLESHEETS folders anymore.

    But, uh, well, Compass.app is for those who didn’t want to deal with the Ruby stuffs! ;)

    • brooke
      Permalink to comment#

      Is it possible for you to explain how you modify the config.rb? When I try to open it, I don’t have to program to support it. I am also using the compass app for Windows. I am totally new at this and am finding it very difficult to find resources for beginners (and having an even harder time for beginners using the compass app).

    • brooke
      Permalink to comment#

      Sorry, I was being dumb. Problem solved. Just needed to right click and open with Sublime Text :) Any other advice you have though, I’d appreciate it :)

    • Chris Wiley
      Permalink to comment#

      Hi Brooke,

      There are several places you can go to learn more about Sass/Compass. Here are a few to get you started.

      http://thesassway.com/beginner

      http://net.tutsplus.com/tutorials/html-css-techniques/mastering-sass-lesson-3/?search_index=2

      And since you mentioned being on Windows, I used this to help set up my environment.

      http://marshallford.me/articles/windows-workflow

      Now that talks about several different things from using a better console and setting up things like version control and sass/compass. I’d just pick and choose the parts you would like to set up.

      I have gotten away from using apps like Prepros and Compass App and started just using the command line. It takes some getting use to but it works well. But I did like Prepros a lot and would recommend that. You can use the free version and it is just awesome. I’d get the pro version if you needed those other features.

      I hope this helps pointing you to some helpful things to start your journey.

  8. This seems mega overkill. How about this?

    http_path = "/"
    css_dir = "."
    sass_dir = "scss"
    images_dir = "images"
    javascripts_dir = "js"
    
    output_style = :compressed
    environment = :development
    

    And it only took changing css to ..

    • I don’t think that works.

      That’s going to compile everything in scss to the root and make a big ol’ sloppy mess in your theme folder root.

    • I guess that’s true if you have to have the rest of the CSS in the css/ folder. But some people may not have multiple stylesheets for a theme they plan on repackaging, etc, or just have the one (compiled) stylesheet. This provides a simple solution. WordPress isn’t the only CMS I’ve come across that does this, but having a specific location a stylesheet has to be and not being able to edit that location is super lame. Another alternative (which has some drawbacks as already discussed, but just so you have options) is to create a symlink, such as this command (run from your theme dir):

      ln -s css/style.css style.css
      

      This would at least allow blog_info('stylesheet_url') to work, but in a repackaged scenario, it may confuse another developer.

      Symlink’s are problematic in CodeKit though.

  9. Tim D.
    Permalink to comment#

    There’s a much easier way to do this, and the way all of my WP themes are set up..

    in config.rb:

     css_dir = ""
    

    then your sass directory (the only important part is the style.scss):

     /sass
        /partials      <-- all imported in style.scss
           _header.scss
           _footer.scss
           _body.scss
        /css            <-- all compiles to /css directory
           ie.scss
           layout.scss
           otherstuff.scss
        style.scss   <-- compiles to root directory as style.css
    
    • Tim D.
      Permalink to comment#

      btw by setting the css_dir to the root directory you can effectively build out your complete directory structure within the /sass directory to mirror your actual project, so if you have stylesheets in your /admin/assets/css directory simply put that same structure in your /sass directory i.e. /sass/admin/assets/css and all .scss files will compile to their correct place..

  10. Permalink to comment#

    I just have an @import in style.css:

    @import url(stylesheets/screen.css);

    in config.rb, I set relative paths to true

  11. Jason
    Permalink to comment#

    I was wrestling with this the other day and didn’t come up with anything this good. Good stuff. I like this approach. You still have your SCSS files all together and it just moves it over while all your other css files stay in the css folder, very cool.

  12. Here is what my config looks like using CodeKit. Seems to work for me. I’m sure I’m missing something though.

    http_path = "/"
    css_dir = ""
    sass_dir = "scss"
    images_dir = "img"
    javascripts_dir = "js"

    A few things it doesn’t do (which I’m willing to overlook):

    Doesn’t keep the standard of having all your css in the css directory.
    All of my scss compiles into one style.css regardless. I’m ok with this but you may not.

    • Totally fine config, but like you said, it doesn’t compile from scss to css. I just refuse to have every single CSS file from scss in my root theme directory. It would be a big mess on several of my projects.

    • Tim D.
      Permalink to comment#

      Chris, any .scss files you have inside a folder in your /sass directory will compile to that directory in your project if you have the css_dir = “” Therefore you can have your scss files compile anywhere you want them to, they won’t compile to the root unless you just leave them sitting at the base of your /sass directory. If you need your files to compile to /yourproject/css then put a /css directory in the sass folder like so /yourproject/sass/css..

      i.e. /yourproject/sass/css/style.scss will compile to /yourproject/css/style.css

      Try it, it’s by far the easiest way to organize your stylesheets, and you have complete control over where they compile to simply by organizing them in the folders they need to compile to relative to your project root in your sass folder.

  13. I didn’t knew that is Sass/Compass in terms of WordPress. But now I am getting it. Thanks for the nice post.. I am trying to implement this and will comment you if need your help..
    Cheerzz..!

  14. In the latest WordPress (3.4.2) you don’t need the comment block at the start of your style.css for it to be recognised, just a folder in your themes directory with an empty index.php and style.css will do.

    • Permalink to comment#

      Ah, that’s good to know, that could prove useful! Is there a link where I can find out more about that?

  15. Darren Grant
    Permalink to comment#

    Hi all,

    I normally have a ‘styles’ directory that compiles into an ‘scss’ directory and a ‘scripts’ directory that minifies into a ‘js’ directory, not using CoffeeScript at the moment but this would work well for that. I also use the approach of the style.css in the root only containing the theme info and not linking in the theme.

    Works pretty well for me!

  16. Subash
    Permalink to comment#

    I use good old @import thing and one thing why are you doing *:after and *:before for box sizing. I wonder why just * { box-sizing: border-box} doesn’t work.

    • Kevin
      Permalink to comment#

      @Madalena: Just the pure ability to make auto generated sprites through Compass when combined with SASS can be all it takes to never go back to plain-old CSS ever again; since you’re using LESS, I can understand staying put with that though…

      The whole JavaScript implementation of LESS is what irks me going with it outside of Compass: Shudder to think what would happen with a browser that disabled JavaScript and I was usiing LESS as a LIVE CSS engine…

  17. Permalink to comment#

    Call me insane, but why not just use standard CSS?

    • If you have to ask that question you clearly haven’t used SASS. It will revolutionise your coding experience and make you so much more efficient.

    • Permalink to comment#

      But, it’s just an extra layer of development you have to worry about. Don’t get me wrong, SASS and LESS are great ideas. But it’s just an extra layer.

    • Madalena
      Permalink to comment#

      I don’t like working with Sass, I too think that is just more stuff to worry about, instead of doing what really matters. Less works fine for me, and it’s awfully simpler. I think that there’re better tools for what sass does, that don’t require so much headache.

      Just my opinion…

      But I can apreciate the very good projects that are made with sass too.

    • Permalink to comment#

      I think that it probably a lot depends on what kind of projects you’re doing, and from what I’ve seen – partly depending on how you work/think.

      For me, I could never move away from using SCSS, because I have, for instance, variables for colours, and I then use Sass functions to change those colours around (darken/lighten/saturate/desaturate, etc). I also use compass a lot for the mixins, since I would go insane if I had to remember the border-radius syntax for the different browsers.

      So, to me, it’s not just another layer that I need to worry about. It’s all that CSS would’ve been in the ideal of worlds =)

    • Madalena
      Permalink to comment#

      Melindrea, I can do all that with Less… the color variables and the darken/lighten too, the mixins… What I meant is that Sass has way too much extra stuff that you don’t really need…

      See by the instalation, to use less, all you need is a compiller, to install sass and compass there are a bunch of other steps. (I admit, i’m lazy and hate to deal with DOS looking screens).

      Maybe I’m just not very well instructed, i don’t know…

    • Permalink to comment#

      @Madalena: I completely agree. But, if I understand tools like SASS and LESS, it emphasizes more of a programming structure to take care of CSS in a more productive fasion? But, I still am going to stick with just Standard CSS, I want to be able to know every CSS property, every prefix, and I want to practice what I preach.

      @Melindrea: I agree as well, simple brochure websites shouldn’t be built upon LESS/SASS because it may take more time, it also will require you to strictly know LESS/SASS.

  18. I’m a bit confused, but I think I figured it out… To use your config.rb script above, you need to have ruby installed on your server, right? Might want to specify that at the start of the article – kinda got my hopes up that there was an easy way to configure it without Ruby.

    I’ve been using CodeKit as a local preprocessor for a few months now, and love it.

    • If you’re compiling Sass anywhere, you’re running Ruby. If you’re using Compass (even through CodeKIt), you for sure have a config.rb file and that’s where the code goes.

    • Right on, Thanks for the clarification.

      I wish running ruby on a server was easier.

  19. Lu Nelson
    Permalink to comment#

    Can’t you set custom output paths on a per-file basis with CodeKit? You can with regular Sass/SCSS…is that disabled when you are using Compass?

  20. Thank you for the tip. Great site.

  21. Rodrigo Ibarra
    Permalink to comment#

    I like using de @import method…
    create a style.scss on the root… open it, @import “/scss/style.scss”; and keep using the scss folder with every single file in it… I use this since I too like to work in bits and pieces so it fits me.

  22. I use Scout to compile my SASS, and that allows me to output my style.css wherever I want it. I had assumed that codekit would allow that too. Doesn’t it?

    • Permalink to comment#

      CodeKit by itself, yes, but Compass has it’s own way of organizing files, so when you use Compass, even in a CodeKit project, it overrides CodeKit.

      If you look at the config.rb in Chris’ post, you’ll see it defines a sass_dir and a css_dir and all sass/scss goes in sass_dir and is outputted to css_dir and you can’t set an output path for individual files.

      That’s what Chris’ post is about: how to get that one style.css in a different dir than css_dir (which is css/) using Compass.

  23. What about using the style.css in the root of your theme just for defining the theme and nothing more?

    You can see my solution here.

  24. Permalink to comment#

    Thanks for the descriptive Tutorial, But i have to learn more about Ruby to try this.

  25. Just tried the ruby work-around using fire.app, just to let others know it will only work after you click “clean & compile” on the app. I think fire.app only runs the config.rb when clean & compiled and not on every stylesheet save. It might be the same for compass.app as they are by the same developer.

    • Praveen Ramachandran
      Permalink to comment#

      I use the Fire.app and it monitors each save on the scss file. It refreshes the browser too though its a wordpress browser. Not sure if this is version dependent as mine is the latest that was released two days back.

      I think earlier days it never used to refresh the browser each time we save as it is wordpress and the url is localhost/domain but the sass files are deep inside localhost/domain/wp-content/themes/my-custom-theme/library/sass

  26. Permalink to comment#

    Hello there,
    Please check my work https://github.com/tokokoo/pondasee I’m building this front-end starter to work with WordPress theme, thought?

  27. Praveen Ramachandran
    Permalink to comment#

    I have been using WordPress Bones starter theme and I like their simple organisation of the files. Every asset is in the ‘library’ folder.

    So, my config.rb file looks like this:
    http_path = “/”
    css_dir = “library/css”
    sass_dir = “library/scss”
    images_dir = “library/images”
    javascripts_dir = “library/js”

    This compliles the scss file into the library/css folder which is enqueued.

  28. Praveen Ramachandran
    Permalink to comment#

    Not sure if the comment appeared as I made a typo in my email address :|

  29. Frank
    Permalink to comment#

    Hi, I have seen some websites and using inspect element in chrome and looking @ their style.css file i don’t see any comment @ top of that file. anyone knows how they are doing that ? a wordpress website without any comments in style.css how is that possible ?

  30. martin
    Permalink to comment#

    Knowing css tricks is always useful. I also know that where you put the css code was always confusing to me as well, especially having in mind that there are multiple ways to do it. Also, the different sources online uses multiple ways so someone who is not that tech savvy can be confused.

    Being that I use a Catalyst development theme for the WordPress development, I use their custom css section which simplifies the whole process. Or for the people that really don’t understand how to implement, you can always use on of the new wordpress template builder drag n’ drop solutions which can help you bypass the whole thing.

  31. I found out that the WP theme’s style.css it a perfect place to put version history, what’s new in this version etc and let the e. g. Compass take care of folder structure to keep things organised; including correct to css files in your header.php (eg screen, print, ie as Compass suggests).

    – not sure if that wouldn’t screw-up child theme compatibility, though.

This comment thread is closed. If you have important information to share, you can always contact me.

*May or may not contain any actual "CSS" or "Tricks".