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:
- There absolutely must be a “style.css” file in the theme folder.
- 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
- Set your config to the even-more-standard of compiling the scss folder into the css folder.
- Move the style.scss folder into the scss folder.
- 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.
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.@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.
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.
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…
@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?
Are you still using CodeKit for compiling everything? I put an
scss
directory in my theme with all of my partials and astyle.scss
that @imports everything. Then in my config.rg, I set it up with:css_dir = "/"
andsass_dir = "scss"
. No extra Ruby code needed and it compiles to style.css in the root of the theme.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.
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.
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:
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.
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
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.
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.
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! ;)
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).
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 :)
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.
This seems mega overkill. How about this?
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):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.
There’s a much easier way to do this, and the way all of my WP themes are set up..
in config.rb:
then your sass directory (the only important part is the style.scss):
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..
I just have an @import in style.css:
@import url(stylesheets/screen.css);
in config.rb, I set relative paths to true
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.
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.
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.
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..!
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 emptyindex.php
andstyle.css
will do.Ah, that’s good to know, that could prove useful! Is there a link where I can find out more about that?
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!
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.
@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…
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.
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.
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.
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 =)
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…
@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.
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.
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?
Thank you for the tip. Great site.
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.
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?
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 asass_dir
and acss_dir
and allsass/scss
goes insass_dir
and is outputted tocss_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 thancss_dir
(which iscss/
) using Compass.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.
Thanks for the descriptive Tutorial, But i have to learn more about Ruby to try this.
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.
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
Hello there,
Please check my work https://github.com/tokokoo/pondasee I’m building this front-end starter to work with WordPress theme, thought?
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.
Not sure if the comment appeared as I made a typo in my email address :|
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 ?
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.
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.