# grunt-contrib-compass v0.9.0 [![Build Status: Linux](https://travis-ci.org/gruntjs/grunt-contrib-compass.png?branch=master)](https://travis-ci.org/gruntjs/grunt-contrib-compass) > Compile Sass to CSS using Compass ## Getting Started This plugin requires Grunt `^0.4.0` If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command: ```shell npm install grunt-contrib-compass --save-dev ``` Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript: ```js grunt.loadNpmTasks('grunt-contrib-compass'); ``` ## Compass task _Run this task with the `grunt compass` command._ [Compass](http://compass-style.org/) is an open-source authoring framework for the [Sass](http://sass-lang.com/) css preprocessor. It helps you build stylesheets faster with a huge library of Sass mixins and functions, advanced tools for spriting, and workflow improvements including file based Sass configuration and a simple pattern for building and using Compass extensions. This task requires you to have [Ruby](http://www.ruby-lang.org/en/downloads/), [Sass](http://sass-lang.com/tutorial.html), and [Compass](http://compass-style.org/install/) >=0.12.2 installed. If you're on OS X or Linux you probably already have Ruby installed; test with `ruby -v` in your terminal. When you've confirmed you have Ruby installed, run `gem update --system && gem install compass` to install Compass and Sass. Compass operates on a folder level. Because of this you don't specify any src/dest, but instead define the `sassDir` and `cssDir` options. ### Options Compass doesn't expose all of its [options][config] through the CLI, which this task makes use of. If you need an option not mentioned below you can either specify a path to a config.rb file in the `config` option or embed it directly into the `raw` option. Options defined in your Gruntfile will override those specified in your config.rb or `raw` property. `config` and `raw` are mutually exclusive. #### config Type: `String` Default: same path as your Gruntfile Specify the location of the Compass [configuration file][config] explicitly. #### raw Type: `String` String form of the Compass [configuration file][config]. #### basePath Type: `String` The path Compass will run from. Defaults to the same path as your Gruntfile. #### banner Type: `String` Prepend the specified string to the output file. Useful for licensing information. **Note:** This only works in combination with the `specify` option and can conflict with sourcemap generation. #### app Type: `String` Default: `stand_alone` Tell compass what kind of application it is integrating with. Can be `stand_alone` or `rails`. #### sassDir Type: `String` The source directory where you keep your Sass stylesheets. #### cssDir Type: `String` The target directory where you keep your CSS stylesheets. #### specify Type: `String|Array` Lets you specify which files you want to compile. Useful if you don't want to compile the whole folder. Globbing supported. Ignores filenames starting with underscore. #### imagesDir Type: `String` The directory where you keep your images. #### javascriptsDir Type: `String` The directory where you keep your JavaScript files. #### fontsDir Type: `String` The directory where you keep your fonts. #### environment Type: `String` Default: `development` Use sensible defaults for your current environment. Can be: `development` or `production` #### outputStyle Type: `String` CSS output mode. Can be: `nested`, `expanded`, `compact`, `compressed`. #### relativeAssets Type: `Boolean` Make Compass asset helpers generate relative urls to assets. #### noLineComments Type: `Boolean` Disable line comments. #### httpPath Type: `String` Default: `/` The path to the project when running within the web server. #### cssPath Type: `String` The directory where the css stylesheets are kept. It is relative to the `projectPath`. Defaults to "stylesheets". #### httpStylesheetsPath Type: `String` Default: `httpPath + "/" + cssDir` The full http path to stylesheets on the web server. #### sassPath Type: `String` Default: `sass` The directory where the sass stylesheets are kept. It is relative to the `projectPath`. #### imagesPath Type: `String` Default: `images` The directory where the images are kept. It is relative to the projectPath. #### httpImagesPath Type: `String` Default: `httpPath + "/" + imagesDir` The full http path to images on the web server. #### generatedImagesDir Type: `String` Default: value of `imagesDir` The directory where generated images are kept. It is relative to the `projectPath`. #### generatedImagesPath Type: `String` Default: value of `projectPath/generatedImagesDir` The full path to where generated images are kept. #### httpGeneratedImagesPath Type: `String` Default: `httpPath + "/" + generatedImagesDir` The full http path to generated images on the web server. #### spriteLoadPath Type: `String|Array` Default: value of `imagesPath` Add additional locations to look for sprites. The imagesPath is always the last entry in this list. #### javascriptsPath Type: `String` Default: `projectPath/javascriptsDir` The full path to where javascripts are kept. #### httpJavascriptsPath Type: `String` Default: `httpPath + "/" + javascriptsDir` The full http path to javascripts on the web server. #### fontsPath Type: `String` Default: `projectPath/fontsDir` The full path to where font files are kept. #### httpFontsPath Type: `String` The full http path to font files on the web server. #### httpFontsDir Type: `String` The relative http path to font files on the web server. #### extensionsPath Type: `String` Default: `project_root/extensions` The full http path to the ad-hoc extensions folder on the web server. This is used to access compass plugins that have been installed directly to the project (e.g. through [Bower](https://github.com/bower/bower)) instead of globally as gems. *Only Compass >=0.12.2* #### extensionsDir Type: `String` The relative http path to the ad-hoc extensions folder on the web server. *Only Compass >=0.12.2* #### assetCacheBuster Type: `Boolean` Default: `true` If set to `false`, this disables the default asset cache buster. #### cacheDir Type: `String` Default: `.sass-cache` The relative path to the folder where the sass cache files are generated. #### require Type: `String|Array` Require the given Ruby library before running commands. This is used to access Compass plugins without having a project configuration file. #### load Type: `String|Array` Load the framework or extensions found in the specified directory. #### loadAll Type: `String|Array` Load all the frameworks or extensions found in the specified directory. #### importPath Type: `String|Array` Makes files under the specified folder findable by Sass's @import directive. #### debugInfo Type: `Boolean` Causes the line number and file where a selector is defined to be emitted into the compiled CSS in a format that can be understood by the browser. Automatically disabled when using `outputStyle: 'compressed'`. #### quiet Type: `Boolean` Quiet mode. #### trace Type: `Boolean` Show a full stacktrace on error. #### force Type: `Boolean` Allows Compass to overwrite existing files. #### dryRun Type: `Boolean` Dry Run. Tells you what it plans to do. #### boring Type: `Boolean` Turn off colorized output. #### bundleExec Type: `Boolean` Run `compass compile` with [bundle exec](http://gembundler.com/v1.3/man/bundle-exec.1.html): `bundle exec compass compile`. #### clean Type: `Boolean` Remove generated files and the sass cache. Runs `compass clean` instead of `compass compile`. #### watch Type: `Boolean` Runs `compass watch` instead of `compass compile`. This will use Compass' native watch command to listen for changes to Sass files and recompile your CSS on changes. While much faster than running `compass compile` each time you want to compile your Sass, Compass becomes a blocking task. This means that if you would like to use it in conjunction with another blocking task, such as `watch`, you will need to use it in conjunction with a paralleling task such as [grunt-concurrent](https://github.com/sindresorhus/grunt-concurrent). [config]: http://compass-style.org/help/tutorials/configuration-reference/ ### Usage Examples #### Example config ```javascript grunt.initConfig({ compass: { // Task dist: { // Target options: { // Target options sassDir: 'sass', cssDir: 'css', environment: 'production' } }, dev: { // Another target options: { sassDir: 'sass', cssDir: 'css' } } } }); grunt.loadNpmTasks('grunt-contrib-compass'); grunt.registerTask('default', ['jshint', 'compass']); ``` #### Example usage ##### Use external config file ```javascript grunt.initConfig({ compass: { dist: { options: { config: 'config/config.rb' } } } }); ``` ##### Override setting in external config file ```javascript grunt.initConfig({ compass: { dist: { options: { config: 'config/config.rb', // css_dir = 'dev/css' cssDir: 'dist/css' } } } }); ``` ##### Use `raw` option ```javascript grunt.initConfig({ compass: { dist: { options: { sassDir: 'sass', cssDir: 'css', raw: 'preferred_syntax = :sass\n' // Use `raw` since it's not directly available } } } }); ``` ## Release History * 2014-09-24   v0.9.0   Add Compass version check to ensure only a supported version is used. * 2014-05-16   v0.8.0   Add `spriteLoadPath` option. * 2014-02-09   v0.7.2   Improve compatibility with Compass 0.13. * 2014-01-26   v0.7.1   Fix `assetCacheBuster` option. * 2013-12-07   v0.7.0   Add `cacheDir` option. * 2013-10-04   v0.6.0   Add `watch` option. Fix Compass errors not propagating. * 2013-08-08   v0.5.0   Add `assetCacheBuster` option. * 2013-07-28   v0.4.1   Fix `banner` option with `.css.scss` files. * 2013-07-19   v0.4.0   Add `banner` option. Show compilation time. * 2013-06-24   v0.3.0   Add `extensionDir` and `extensionPath` options. *Requires Compass >=0.12.2*. * 2013-04-11   v0.2.0   Add `clean` option. Expose `raw` options as Grunt options. Fix detection of `Nothing to compile` situation. * 2013-02-27   v0.1.3   Fixes bundleExec. * 2013-02-17   v0.1.2   Ensure Gruntfile.js is included on npm. * 2013-02-15   v0.1.1   First official release for Grunt 0.4.0. * 2013-02-05   v0.1.1rc8   Added new options: basePath specify, debugInfo. * 2013-01-25   v0.1.1rc7   Updating grunt/gruntplugin dependencies to rc7. Changing in-development grunt/gruntplugin dependency versions from tilde version ranges to specific versions. * 2013-01-10   v0.1.1rc5   Updating to work with grunt v0.4.0rc5. * 2012-10-22   v0.1.0   Initial release --- Task submitted by [Sindre Sorhus](http://github.com/sindresorhus) *This file was generated on Tue Jun 24 2014 22:15:11.*