1 # grunt-contrib-compass v1.1.1 [![Build Status: Linux](https://travis-ci.org/gruntjs/grunt-contrib-compass.svg?branch=master)](https://travis-ci.org/gruntjs/grunt-contrib-compass)
3 > Compile Sass to CSS using Compass
9 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:
12 npm install grunt-contrib-compass --save-dev
15 Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
18 grunt.loadNpmTasks('grunt-contrib-compass');
25 _Run this task with the `grunt compass` command._
27 [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.
29 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/) >=1.0.1 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.
31 Compass operates on a folder level. Because of this you don't specify any src/dest, but instead define the `sassDir` and `cssDir` options.
35 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.
47 Default: same path as your Gruntfile
49 Specify the location of the Compass [configuration file][config] explicitly.
55 String form of the Compass [configuration file][config].
61 The path Compass will run from. Defaults to the same path as your Gruntfile.
67 Prepend the specified string to the output file. Useful for licensing
68 information. **Note:** This only works in combination with the `specify` option
69 and can conflict with sourcemap generation.
74 Default: `stand_alone`
76 Tell compass what kind of application it is integrating with. Can be `stand_alone` or `rails`.
82 The source directory where you keep your Sass stylesheets.
88 The target directory where you keep your CSS stylesheets.
94 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. Paths are relative to the Gruntfile.
100 The directory where you keep your images.
106 The directory where you keep your JavaScript files.
112 The directory where you keep your fonts.
117 Default: `development`
119 Use sensible defaults for your current environment. Can be: `development` or `production`
125 CSS output mode. Can be: `nested`, `expanded`, `compact`, `compressed`.
131 Make Compass asset helpers generate relative urls to assets.
137 Disable line comments.
144 The path to the project when running within the web server.
150 The directory where the css stylesheets are kept. It is relative to the `projectPath`. Defaults to "stylesheets".
152 #### httpStylesheetsPath
155 Default: `httpPath + "/" + cssDir`
157 The full http path to stylesheets on the web server.
164 The directory where the sass stylesheets are kept. It is relative to the `projectPath`.
171 The directory where the images are kept. It is relative to the projectPath.
176 Default: `httpPath + "/" + imagesDir`
178 The full http path to images on the web server.
180 #### generatedImagesDir
183 Default: value of `imagesDir`
185 The directory where generated images are kept. It is relative to the `projectPath`.
187 #### generatedImagesPath
190 Default: value of `projectPath/generatedImagesDir`
192 The full path to where generated images are kept.
194 #### httpGeneratedImagesPath
197 Default: `httpPath + "/" + generatedImagesDir`
199 The full http path to generated images on the web server.
204 Default: value of `imagesPath`
206 Add additional locations to look for sprites. The imagesPath is always the last entry in this list.
211 Default: `projectPath/javascriptsDir`
213 The full path to where javascripts are kept.
215 #### httpJavascriptsPath
218 Default: `httpPath + "/" + javascriptsDir`
220 The full http path to javascripts on the web server.
225 Default: `projectPath/fontsDir`
227 The full path to where font files are kept.
233 The full http path to font files on the web server.
239 The relative http path to font files on the web server.
244 Default: `project_root/extensions`
246 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*
252 The relative http path to the ad-hoc extensions folder on the web server. *Only Compass >=0.12.2*
254 #### assetCacheBuster
259 If set to `false`, this disables the default asset cache buster.
264 Default: `.sass-cache`
266 The relative path to the folder where the sass cache files are generated.
272 Require the given Ruby library before running commands. This is used to access Compass plugins without having a project configuration file.
278 Load the framework or extensions found in the specified directory.
284 Load all the frameworks or extensions found in the specified directory.
290 Makes files under the specified folder findable by Sass's @import directive.
296 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'`.
308 Show a full stacktrace on error.
314 Allows Compass to overwrite existing files.
320 Turn off colorized output.
326 Run `compass compile` with [bundle exec](http://gembundler.com/v1.3/man/bundle-exec.1.html): `bundle exec compass compile`.
332 Remove generated files and the sass cache. Runs `compass clean` instead of `compass compile`.
338 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).
341 [config]: http://compass-style.org/help/documentation/configuration-reference/
351 options: { // Target options
354 environment: 'production'
357 dev: { // Another target
366 grunt.loadNpmTasks('grunt-contrib-compass');
368 grunt.registerTask('default', ['jshint', 'compass']);
375 ##### Use external config file
382 config: 'config/config.rb'
389 ##### Override setting in external config file
396 config: 'config/config.rb', // css_dir = 'dev/css'
404 ##### Use `raw` option
413 raw: 'preferred_syntax = :sass\n' // Use `raw` since it's not directly available
423 * 2016-03-04 v1.1.1 pass only compass package name, not full path
424 * 2016-02-15 v1.1.0 Use `which` to find compass binary cross platform. Update async and tmp dependencies.
425 * 2015-09-29 v1.0.4 Use the `compass` flag for the `httpPath` option. Use single-quotes in the config.rb generated file.
426 * 2015-04-02 v1.0.3 Add `--config` path before `--` option/argument separator.
427 * 2015-03-31 v1.0.2 Improve POSIX compliance.
428 * 2014-09-08 v1.0.1 Use compass long flag for `importPath`
429 * 2014-09-05 v1.0.0 Fix `bundleExec` option on Windows.
430 * 2014-07-31 v0.9.1 Fixes npm peerDependency warnings.
431 * 2014-06-24 v0.9.0 Add Compass version check to ensure only a supported version is used.
432 * 2014-05-16 v0.8.0 Add `spriteLoadPath` option.
433 * 2014-02-09 v0.7.2 Improve compatibility with Compass 0.13.
434 * 2014-01-26 v0.7.1 Fix `assetCacheBuster` option.
435 * 2013-12-07 v0.7.0 Add `cacheDir` option.
436 * 2013-10-04 v0.6.0 Add `watch` option. Fix Compass errors not propagating.
437 * 2013-08-08 v0.5.0 Add `assetCacheBuster` option.
438 * 2013-07-28 v0.4.1 Fix `banner` option with `.css.scss` files.
439 * 2013-07-19 v0.4.0 Add `banner` option. Show compilation time.
440 * 2013-06-24 v0.3.0 Add `extensionDir` and `extensionPath` options. *Requires Compass >=0.12.2*.
441 * 2013-04-11 v0.2.0 Add `clean` option. Expose `raw` options as Grunt options. Fix detection of `Nothing to compile` situation.
442 * 2013-02-27 v0.1.3 Fixes bundleExec.
443 * 2013-02-17 v0.1.2 Ensure Gruntfile.js is included on npm.
444 * 2013-02-15 v0.1.1 First official release for Grunt 0.4.0.
445 * 2013-02-05 v0.1.1rc8 Added new options: basePath specify, debugInfo.
446 * 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.
447 * 2013-01-10 v0.1.1rc5 Updating to work with grunt v0.4.0rc5.
448 * 2012-10-22 v0.1.0 Initial release
452 Task submitted by [Sindre Sorhus](http://github.com/sindresorhus)
454 *This file was generated on Fri Mar 04 2016 16:24:46.*