www.aleph1.co.uk Git - yaffs-website/blob - node_modules/grunt-contrib-compass/README.md

   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)
   2
   3 > Compile Sass to CSS using Compass
   4
   5
   6
   7 ## Getting Started
   8
   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:
  10
  11 ```shell
  12 npm install grunt-contrib-compass --save-dev
  13 ```
  14
  15 Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
  16
  17 ```js
  18 grunt.loadNpmTasks('grunt-contrib-compass');
  19 ```
  20
  21
  22
  23
  24 ## Compass task
  25 _Run this task with the `grunt compass` command._
  26
  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.
  28
  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.
  30
  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.
  32
  33 ### Options
  34
  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.
  36
  37 #### sourcemap
  38
  39 Type: `Boolean`
  40 Default: `false`
  41
  42 Generate Source Maps.
  43
  44 #### config
  45
  46 Type: `String`
  47 Default: same path as your Gruntfile
  48
  49 Specify the location of the Compass [configuration file][config] explicitly.
  50
  51 #### raw
  52
  53 Type: `String`
  54
  55 String form of the Compass [configuration file][config].
  56
  57 #### basePath
  58
  59 Type: `String`
  60
  61 The path Compass will run from. Defaults to the same path as your Gruntfile.
  62
  63 #### banner
  64
  65 Type: `String`
  66
  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.
  70
  71 #### app
  72
  73 Type: `String`
  74 Default: `stand_alone`
  75
  76 Tell compass what kind of application it is integrating with. Can be `stand_alone` or `rails`.
  77
  78 #### sassDir
  79
  80 Type: `String`
  81
  82 The source directory where you keep your Sass stylesheets.
  83
  84 #### cssDir
  85
  86 Type: `String`
  87
  88 The target directory where you keep your CSS stylesheets.
  89
  90 #### specify
  91
  92 Type: `String|Array`
  93
  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.
  95
  96 #### imagesDir
  97
  98 Type: `String`
  99
 100 The directory where you keep your images.
 101
 102 #### javascriptsDir
 103
 104 Type: `String`
 105
 106 The directory where you keep your JavaScript files.
 107
 108 #### fontsDir
 109
 110 Type: `String`
 111
 112 The directory where you keep your fonts.
 113
 114 #### environment
 115
 116 Type: `String`
 117 Default: `development`
 118
 119 Use sensible defaults for your current environment. Can be: `development` or `production`
 120
 121 #### outputStyle
 122
 123 Type: `String`
 124
 125 CSS output mode. Can be: `nested`, `expanded`, `compact`, `compressed`.
 126
 127 #### relativeAssets
 128
 129 Type: `Boolean`
 130
 131 Make Compass asset helpers generate relative urls to assets.
 132
 133 #### noLineComments
 134
 135 Type: `Boolean`
 136
 137 Disable line comments.
 138
 139 #### httpPath
 140
 141 Type: `String`
 142 Default: `/`
 143
 144 The path to the project when running within the web server.
 145
 146 #### cssPath
 147
 148 Type: `String`
 149
 150 The directory where the css stylesheets are kept. It is relative to the `projectPath`. Defaults to "stylesheets".
 151
 152 #### httpStylesheetsPath
 153
 154 Type: `String`
 155 Default: `httpPath + "/" + cssDir`
 156
 157 The full http path to stylesheets on the web server.
 158
 159 #### sassPath
 160
 161 Type: `String`
 162 Default: `sass`
 163
 164 The directory where the sass stylesheets are kept. It is relative to the `projectPath`.
 165
 166 #### imagesPath
 167
 168 Type: `String`
 169 Default: `images`
 170
 171 The directory where the images are kept. It is relative to the projectPath.
 172
 173 #### httpImagesPath
 174
 175 Type: `String`
 176 Default: `httpPath + "/" + imagesDir`
 177
 178 The full http path to images on the web server.
 179
 180 #### generatedImagesDir
 181
 182 Type: `String`
 183 Default: value of `imagesDir`
 184
 185 The directory where generated images are kept. It is relative to the `projectPath`.
 186
 187 #### generatedImagesPath
 188
 189 Type: `String`
 190 Default: value of `projectPath/generatedImagesDir`
 191
 192 The full path to where generated images are kept.
 193
 194 #### httpGeneratedImagesPath
 195
 196 Type: `String`
 197 Default: `httpPath + "/" + generatedImagesDir`
 198
 199 The full http path to generated images on the web server.
 200
 201 #### spriteLoadPath
 202
 203 Type: `String|Array`
 204 Default: value of `imagesPath`
 205
 206 Add additional locations to look for sprites. The imagesPath is always the last entry in this list.
 207
 208 #### javascriptsPath
 209
 210 Type: `String`
 211 Default: `projectPath/javascriptsDir`
 212
 213 The full path to where javascripts are kept.
 214
 215 #### httpJavascriptsPath
 216
 217 Type: `String`
 218 Default: `httpPath + "/" + javascriptsDir`
 219
 220 The full http path to javascripts on the web server.
 221
 222 #### fontsPath
 223
 224 Type: `String`
 225 Default: `projectPath/fontsDir`
 226
 227 The full path to where font files are kept.
 228
 229 #### httpFontsPath
 230
 231 Type: `String`
 232
 233 The full http path to font files on the web server.
 234
 235 #### httpFontsDir
 236
 237 Type: `String`
 238
 239 The relative http path to font files on the web server.
 240
 241 #### extensionsPath
 242
 243 Type: `String`
 244 Default: `project_root/extensions`
 245
 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*
 247
 248 #### extensionsDir
 249
 250 Type: `String`
 251
 252 The relative http path to the ad-hoc extensions folder on the web server. *Only Compass >=0.12.2*
 253
 254 #### assetCacheBuster
 255
 256 Type: `Boolean`
 257 Default: `true`
 258
 259 If set to `false`, this disables the default asset cache buster.
 260
 261 #### cacheDir
 262
 263 Type: `String`
 264 Default: `.sass-cache`
 265
 266 The relative path to the folder where the sass cache files are generated.
 267
 268 #### require
 269
 270 Type: `String|Array`
 271
 272 Require the given Ruby library before running commands. This is used to access Compass plugins without having a project configuration file.
 273
 274 #### load
 275
 276 Type: `String|Array`
 277
 278 Load the framework or extensions found in the specified directory.
 279
 280 #### loadAll
 281
 282 Type: `String|Array`
 283
 284 Load all the frameworks or extensions found in the specified directory.
 285
 286 #### importPath
 287
 288 Type: `String|Array`
 289
 290 Makes files under the specified folder findable by Sass's @import directive.
 291
 292 #### debugInfo
 293
 294 Type: `Boolean`
 295
 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'`.
 297
 298 #### quiet
 299
 300 Type: `Boolean`
 301
 302 Quiet mode.
 303
 304 #### trace
 305
 306 Type: `Boolean`
 307
 308 Show a full stacktrace on error.
 309
 310 #### force
 311
 312 Type: `Boolean`
 313
 314 Allows Compass to overwrite existing files.
 315
 316 #### boring
 317
 318 Type: `Boolean`
 319
 320 Turn off colorized output.
 321
 322 #### bundleExec
 323
 324 Type: `Boolean`
 325
 326 Run `compass compile` with [bundle exec](http://gembundler.com/v1.3/man/bundle-exec.1.html): `bundle exec compass compile`.
 327
 328 #### clean
 329
 330 Type: `Boolean`
 331
 332 Remove generated files and the sass cache. Runs `compass clean` instead of `compass compile`.
 333
 334 #### watch
 335
 336 Type: `Boolean`
 337
 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).
 339
 340
 341 [config]: http://compass-style.org/help/documentation/configuration-reference/
 342
 343 ### Usage Examples
 344
 345 #### Example config
 346
 347 ```js
 348 grunt.initConfig({
 349   compass: {                  // Task
 350     dist: {                   // Target
 351       options: {              // Target options
 352         sassDir: 'sass',
 353         cssDir: 'css',
 354         environment: 'production'
 355       }
 356     },
 357     dev: {                    // Another target
 358       options: {
 359         sassDir: 'sass',
 360         cssDir: 'css'
 361       }
 362     }
 363   }
 364 });
 365
 366 grunt.loadNpmTasks('grunt-contrib-compass');
 367
 368 grunt.registerTask('default', ['jshint', 'compass']);
 369 ```
 370
 371
 372 #### Example usage
 373
 374
 375 ##### Use external config file
 376
 377 ```js
 378 grunt.initConfig({
 379   compass: {
 380     dist: {
 381       options: {
 382         config: 'config/config.rb'
 383       }
 384     }
 385   }
 386 });
 387 ```
 388
 389 ##### Override setting in external config file
 390
 391 ```js
 392 grunt.initConfig({
 393   compass: {
 394     dist: {
 395       options: {
 396         config: 'config/config.rb',  // css_dir = 'dev/css'
 397         cssDir: 'dist/css'
 398       }
 399     }
 400   }
 401 });
 402 ```
 403
 404 ##### Use `raw` option
 405
 406 ```js
 407 grunt.initConfig({
 408   compass: {
 409     dist: {
 410       options: {
 411         sassDir: 'sass',
 412         cssDir: 'css',
 413         raw: 'preferred_syntax = :sass\n' // Use `raw` since it's not directly available
 414       }
 415     }
 416   }
 417 });
 418 ```
 419
 420
 421 ## Release History
 422
 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
 449
 450 ---
 451
 452 Task submitted by [Sindre Sorhus](http://github.com/sindresorhus)
 453
 454 *This file was generated on Fri Mar 04 2016 16:24:46.*