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

   1 # grunt-contrib-sass v1.0.0 [![Build Status: Linux](https://travis-ci.org/gruntjs/grunt-contrib-sass.svg?branch=master)](https://travis-ci.org/gruntjs/grunt-contrib-sass)
   2
   3 > Compile Sass to CSS
   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-sass --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-sass');
  19 ```
  20
  21
  22
  23
  24 ## Sass task
  25 _Run this task with the `grunt sass` command._
  26
  27 [Sass](http://sass-lang.com) is a preprocessor that adds nested rules, variables, mixins and functions, selector inheritance, and more to CSS. Sass files compile into well-formatted, standard CSS to use in your site or application.
  28
  29 This task requires you to have [Ruby](http://www.ruby-lang.org/en/downloads/) and [Sass](http://sass-lang.com/download.html) 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 install sass` to install Sass.
  30
  31 Note: Files that begin with "_" are ignored even if they match the globbing pattern. This is done to match the expected [Sass partial behaviour](http://sass-lang.com/documentation/file.SASS_REFERENCE.html#partials).
  32
  33 ### Options
  34
  35
  36 #### sourcemap
  37
  38 Type: `String`
  39 Default: `auto`
  40
  41 Values:
  42
  43 - `auto` - relative paths where possible, file URIs elsewhere
  44 - `file` - always absolute file URIs
  45 - `inline` - include the source text in the sourcemap
  46 - `none`- no sourcemaps
  47
  48 **Requires Sass 3.4.0, which can be installed with `gem install sass`**
  49
  50
  51 #### trace
  52
  53 Type: `Boolean`
  54 Default: `false`
  55
  56 Show a full traceback on error.
  57
  58
  59 #### unixNewlines
  60
  61 Type: `Boolean`
  62 Default: `false` on Windows, otherwise `true`
  63
  64 Force Unix newlines in written files.
  65
  66
  67 #### check
  68
  69 Type: `Boolean`
  70 Default: `false`
  71
  72 Just check the Sass syntax, does not evaluate and write the output.
  73
  74
  75 #### style
  76
  77 Type: `String`
  78 Default: `nested`
  79
  80 Output style. Can be `nested`, `compact`, `compressed`, `expanded`.
  81
  82
  83 #### precision
  84
  85 Type: `Number`
  86 Default: `5`
  87
  88 How many digits of precision to use when outputting decimal numbers.
  89
  90
  91 #### quiet
  92
  93 Type: `Boolean`
  94 Default: `false`
  95
  96 Silence warnings and status messages during compilation.
  97
  98
  99 #### compass
 100
 101 Type: `Boolean`
 102 Default: `false`
 103
 104 Make Compass imports available and load project configuration (`config.rb` located close to the `Gruntfile.js`).
 105
 106
 107 #### debugInfo
 108
 109 Type: `Boolean`
 110 Default: `false`
 111
 112 Emit extra information in the generated CSS that can be used by the FireSass Firebug plugin.
 113
 114
 115 #### lineNumbers
 116
 117 Type: `Boolean`
 118 Default: `false`
 119
 120 Emit comments in the generated CSS indicating the corresponding source line.
 121
 122
 123 #### loadPath
 124
 125 Type: `String|Array`
 126
 127 Add a (or multiple) Sass import path.
 128
 129
 130 #### require
 131
 132 Type: `String|Array`
 133
 134 Require a (or multiple) Ruby library before running Sass.
 135
 136
 137 #### cacheLocation
 138
 139 Type: `String`
 140 Default: `.sass-cache`
 141
 142 The path to put cached Sass files.
 143
 144
 145 #### noCache
 146
 147 Type: `Boolean`
 148 Default: `false`
 149
 150 Don't cache to sassc files.
 151
 152
 153 #### bundleExec
 154
 155 Type: `Boolean`
 156 Default: `false`
 157
 158 Run `sass` with [bundle exec](http://gembundler.com/man/bundle-exec.1.html): `bundle exec sass`.
 159
 160
 161 #### update
 162
 163 Type: `Boolean`
 164 Default: `false`
 165
 166 Only compile changed files.
 167
 168 ### Examples
 169
 170 #### Example config
 171
 172 ```js
 173 grunt.initConfig({
 174   sass: {                              // Task
 175     dist: {                            // Target
 176       options: {                       // Target options
 177         style: 'expanded'
 178       },
 179       files: {                         // Dictionary of files
 180         'main.css': 'main.scss',       // 'destination': 'source'
 181         'widgets.css': 'widgets.scss'
 182       }
 183     }
 184   }
 185 });
 186
 187 grunt.loadNpmTasks('grunt-contrib-sass');
 188
 189 grunt.registerTask('default', ['sass']);
 190 ```
 191
 192 #### Compile
 193
 194 ```js
 195 grunt.initConfig({
 196   sass: {
 197     dist: {
 198       files: {
 199         'main.css': 'main.scss'
 200       }
 201     }
 202   }
 203 });
 204 ```
 205
 206 #### Concat and compile
 207
 208 Instead of concatenating the files, just `@import` them into another `.sass` file eg. `main.scss`.
 209
 210
 211 #### Compile multiple files
 212
 213 You can specify multiple `destination: source` items in `files`.
 214
 215 ```js
 216 grunt.initConfig({
 217   sass: {
 218     dist: {
 219       files: {
 220         'main.css': 'main.scss',
 221         'widgets.css': 'widgets.scss'
 222       }
 223     }
 224   }
 225 });
 226 ```
 227
 228 #### Compile files in a directory
 229
 230 Instead of naming all files you want to compile, you can use the `expand` property allowing you to specify a directory. More information available in the [grunt docs](http://gruntjs.com/configuring-tasks) - `Building the files object dynamically`.
 231
 232 ```js
 233 grunt.initConfig({
 234   sass: {
 235     dist: {
 236       files: [{
 237         expand: true,
 238         cwd: 'styles',
 239         src: ['*.scss'],
 240         dest: '../public',
 241         ext: '.css'
 242       }]
 243     }
 244   }
 245 });
 246 ```
 247
 248
 249 ## Release History
 250
 251  * 2016-03-04   v1.0.0   bump `chalk`. update to docs and project structure.
 252  * 2015-02-06   v0.9.0   Remove `banner` option. Allow using `--force` to ignore compile errors. Increase concurrency count from `2` to `4`. Improve Windows support.
 253  * 2014-08-24   v0.8.1   Fix `check` option.
 254  * 2014-08-21   v0.8.0   Support Sass 3.4 Source Map option. Add `update` option.
 255  * 2014-08-09   v0.7.4   Fix bundleExec option. Fix `os.cpus()` issue. Log `sass` command when `--verbose` flag is set.
 256  * 2014-03-06   v0.7.3   Only create empty dest files when they don't already exist.
 257  * 2014-02-02   v0.7.2   Fix error reporting when Sass is not available.
 258  * 2014-01-28   v0.7.1   Fix regression of Bundler support.
 259  * 2014-01-26   v0.7.0   Improve Windows support.
 260  * 2013-12-10   v0.6.0   Ignore files where filename have leading underscore.
 261  * 2013-08-21   v0.5.0   Add banner option.
 262  * 2013-07-06   v0.4.1   Use file.orig.src if file.src does not exist and return early to avoid passing non-existent files to sass binary.
 263  * 2013-06-30   v0.4.0   Rewrite task to be able to support Source Maps. Compile Sass files in parallel for better performance.
 264  * 2013-03-26   v0.3.0   Add support for `bundle exec`. Make sure `.css` files are compiled with SCSS.
 265  * 2013-02-15   v0.2.2   First official release for Grunt 0.4.0.
 266  * 2013-01-25   v0.2.2rc7   Updating grunt/gruntplugin dependencies to rc7. Changing in-development grunt/gruntplugin dependency versions from tilde version ranges to specific versions.
 267  * 2013-01-09   v0.2.2rc5   Updating to work with grunt v0.4.0rc5. Switching to this.files api. Add separator option.
 268  * 2012-11-05   v0.2.0   Grunt 0.4 compatibility. Improve error message when Sass binary couldn't be found
 269  * 2012-10-12   v0.1.3   Rename grunt-contrib-lib dep to grunt-lib-contrib.
 270  * 2012-10-08   v0.1.2   Fix regression for darwin.
 271  * 2012-10-05   v0.1.1   Windows support.
 272  * 2012-09-24   v0.1.0   Initial release.
 273
 274 ---
 275
 276 Task submitted by [Sindre Sorhus](https://github.com/sindresorhus)
 277
 278 *This file was generated on Fri Mar 04 2016 15:57:01.*