Compile Sass to CSS using Compass
npm install grunt-contrib-compass> Compile Sass to CSS using Compass
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a 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');
command._Compass is an open-source authoring framework for the Sass 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, Sass, and Compass >=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.Compass operates on a folder level. Because of this you don't specify any src/dest, but instead define the
sassDir and cssDir options.$3
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.#### sourcemap
Type:
Boolean
Default: falseGenerate Source Maps.
#### config
Type:
String
Default: same path as your GruntfileSpecify the location of the Compass [configuration file][config] explicitly.
#### raw
Type:
StringString form of the Compass [configuration file][config].
#### basePath
Type:
StringThe path Compass will run from. Defaults to the same path as your Gruntfile.
#### banner
Type:
StringPrepend 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_aloneTell compass what kind of application it is integrating with. Can be
stand_alone or rails.#### sassDir
Type:
StringThe source directory where you keep your Sass stylesheets.
#### cssDir
Type:
StringThe target directory where you keep your CSS stylesheets.
#### specify
Type:
String|ArrayLets 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.
#### imagesDir
Type:
StringThe directory where you keep your images.
#### javascriptsDir
Type:
StringThe directory where you keep your JavaScript files.
#### fontsDir
Type:
StringThe directory where you keep your fonts.
#### environment
Type:
String
Default: developmentUse sensible defaults for your current environment. Can be:
development or production#### outputStyle
Type:
StringCSS output mode. Can be:
nested, expanded, compact, compressed.#### relativeAssets
Type:
BooleanMake Compass asset helpers generate relative urls to assets.
#### noLineComments
Type:
BooleanDisable line comments.
#### httpPath
Type:
String
Default: /The path to the project when running within the web server.
#### cssPath
Type:
StringThe directory where the css stylesheets are kept. It is relative to the
projectPath. Defaults to "stylesheets".#### httpStylesheetsPath
Type:
String
Default: httpPath + "/" + cssDirThe full http path to stylesheets on the web server.
#### sassPath
Type:
String
Default: sassThe directory where the sass stylesheets are kept. It is relative to the
projectPath.#### imagesPath
Type:
String
Default: imagesThe directory where the images are kept. It is relative to the projectPath.
#### httpImagesPath
Type:
String
Default: httpPath + "/" + imagesDirThe full http path to images on the web server.
#### generatedImagesDir
Type:
String
Default: value of imagesDirThe directory where generated images are kept. It is relative to the
projectPath.#### generatedImagesPath
Type:
String
Default: value of projectPath/generatedImagesDirThe full path to where generated images are kept.
#### httpGeneratedImagesPath
Type:
String
Default: httpPath + "/" + generatedImagesDirThe full http path to generated images on the web server.
#### spriteLoadPath
Type:
String|Array
Default: value of imagesPathAdd additional locations to look for sprites. The imagesPath is always the last entry in this list.
#### javascriptsPath
Type:
String
Default: projectPath/javascriptsDirThe full path to where javascripts are kept.
#### httpJavascriptsPath
Type:
String
Default: httpPath + "/" + javascriptsDirThe full http path to javascripts on the web server.
#### fontsPath
Type:
String
Default: projectPath/fontsDirThe full path to where font files are kept.
#### httpFontsPath
Type:
StringThe full http path to font files on the web server.
#### httpFontsDir
Type:
StringThe relative http path to font files on the web server.
#### extensionsPath
Type:
String
Default: project_root/extensionsThe 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) instead of globally as gems. Only Compass >=0.12.2
#### extensionsDir
Type:
StringThe relative http path to the ad-hoc extensions folder on the web server. Only Compass >=0.12.2
#### assetCacheBuster
Type:
Boolean
Default: trueIf set to
false, this disables the default asset cache buster.#### cacheDir
Type:
String
Default: .sass-cacheThe relative path to the folder where the sass cache files are generated.
#### require
Type:
String|ArrayRequire the given Ruby library before running commands. This is used to access Compass plugins without having a project configuration file.
#### load
Type:
String|ArrayLoad the framework or extensions found in the specified directory.
#### loadAll
Type:
String|ArrayLoad all the frameworks or extensions found in the specified directory.
#### importPath
Type:
String|ArrayMakes files under the specified folder findable by Sass's @import directive.
#### debugInfo
Type:
BooleanCauses 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:
BooleanQuiet mode.
#### trace
Type:
BooleanShow a full stacktrace on error.
#### force
Type:
BooleanAllows Compass to overwrite existing files.
#### boring
Type:
BooleanTurn off colorized output.
#### bundleExec
Type:
BooleanRun
compass compile with bundle exec: bundle exec compass compile.#### clean
Type:
BooleanRemove generated files and the sass cache. Runs
compass clean instead of compass compile.#### watch
Type:
BooleanRuns
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.
[config]: http://compass-style.org/help/documentation/configuration-reference/
$3
#### Example config
`js
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
`js
grunt.initConfig({
compass: {
dist: {
options: {
config: 'config/config.rb'
}
}
}
});
`##### Override setting in external config file
`js
grunt.initConfig({
compass: {
dist: {
options: {
config: 'config/config.rb', // css_dir = 'dev/css'
cssDir: 'dist/css'
}
}
}
});
`##### Use
raw option`js
grunt.initConfig({
compass: {
dist: {
options: {
sassDir: 'sass',
cssDir: 'css',
raw: 'preferred_syntax = :sass\n' // Use raw since it's not directly available
}
}
}
});
`
Release History
* 2016-03-04 v1.1.1 pass only compass package name, not full path
* 2016-02-15 v1.1.0 Use
which to find compass binary cross platform. Update async and tmp dependencies.
* 2015-09-29 v1.0.4 Use the compass flag for the httpPath option. Use single-quotes in the config.rb generated file.
* 2015-04-02 v1.0.3 Add --config path before -- option/argument separator.
* 2015-03-31 v1.0.2 Improve POSIX compliance.
* 2014-09-08 v1.0.1 Use compass long flag for importPath
* 2014-09-05 v1.0.0 Fix bundleExec option on Windows.
* 2014-07-31 v0.9.1 Fixes npm peerDependency warnings.
* 2014-06-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.---
Task submitted by Sindre Sorhus
This file was generated on Fri Mar 04 2016 16:24:46.