1 | # grunt-contrib-sass v0.9.2 [![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 | This plugin requires Grunt `>=0.4.0`
|
9 |
|
10 | 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:
|
11 |
|
12 | ```shell
|
13 | npm install grunt-contrib-sass --save-dev
|
14 | ```
|
15 |
|
16 | Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
|
17 |
|
18 | ```js
|
19 | grunt.loadNpmTasks('grunt-contrib-sass');
|
20 | ```
|
21 |
|
22 |
|
23 |
|
24 |
|
25 | ## Sass task
|
26 | _Run this task with the `grunt sass` command._
|
27 |
|
28 | [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.
|
29 |
|
30 | 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.
|
31 |
|
32 | 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).
|
33 |
|
34 | ### Options
|
35 |
|
36 |
|
37 | #### sourcemap
|
38 |
|
39 | Type: `String`
|
40 | Default: `auto`
|
41 |
|
42 | Values:
|
43 |
|
44 | - `auto` - relative paths where possible, file URIs elsewhere
|
45 | - `file` - always absolute file URIs
|
46 | - `inline` - include the source text in the sourcemap
|
47 | - `none`- no sourcemaps
|
48 |
|
49 | **Requires Sass 3.4.0, which can be installed with `gem install sass`**
|
50 |
|
51 |
|
52 | #### trace
|
53 |
|
54 | Type: `Boolean`
|
55 | Default: `false`
|
56 |
|
57 | Show a full traceback on error.
|
58 |
|
59 |
|
60 | #### unixNewlines
|
61 |
|
62 | Type: `Boolean`
|
63 | Default: `false` on Windows, otherwise `true`
|
64 |
|
65 | Force Unix newlines in written files.
|
66 |
|
67 |
|
68 | #### check
|
69 |
|
70 | Type: `Boolean`
|
71 | Default: `false`
|
72 |
|
73 | Just check the Sass syntax, does not evaluate and write the output.
|
74 |
|
75 |
|
76 | #### style
|
77 |
|
78 | Type: `String`
|
79 | Default: `nested`
|
80 |
|
81 | Output style. Can be `nested`, `compact`, `compressed`, `expanded`.
|
82 |
|
83 |
|
84 | #### precision
|
85 |
|
86 | Type: `Number`
|
87 | Default: `5`
|
88 |
|
89 | How many digits of precision to use when outputting decimal numbers.
|
90 |
|
91 |
|
92 | #### quiet
|
93 |
|
94 | Type: `Boolean`
|
95 | Default: `false`
|
96 |
|
97 | Silence warnings and status messages during compilation.
|
98 |
|
99 |
|
100 | #### compass
|
101 |
|
102 | Type: `Boolean`
|
103 | Default: `false`
|
104 |
|
105 | Make Compass imports available and load project configuration (`config.rb` located close to the `Gruntfile.js`).
|
106 |
|
107 |
|
108 | #### debugInfo
|
109 |
|
110 | Type: `Boolean`
|
111 | Default: `false`
|
112 |
|
113 | Emit extra information in the generated CSS that can be used by the FireSass Firebug plugin.
|
114 |
|
115 |
|
116 | #### lineNumbers
|
117 |
|
118 | Type: `Boolean`
|
119 | Default: `false`
|
120 |
|
121 | Emit comments in the generated CSS indicating the corresponding source line.
|
122 |
|
123 |
|
124 | #### loadPath
|
125 |
|
126 | Type: `String|Array`
|
127 |
|
128 | Add a (or multiple) Sass import path.
|
129 |
|
130 |
|
131 | #### require
|
132 |
|
133 | Type: `String|Array`
|
134 |
|
135 | Require a (or multiple) Ruby library before running Sass.
|
136 |
|
137 |
|
138 | #### cacheLocation
|
139 |
|
140 | Type: `String`
|
141 | Default: `.sass-cache`
|
142 |
|
143 | The path to put cached Sass files.
|
144 |
|
145 |
|
146 | #### noCache
|
147 |
|
148 | Type: `Boolean`
|
149 | Default: `false`
|
150 |
|
151 | Don't cache to sassc files.
|
152 |
|
153 |
|
154 | #### bundleExec
|
155 |
|
156 | Type: `Boolean`
|
157 | Default: `false`
|
158 |
|
159 | Run `sass` with [bundle exec](http://gembundler.com/man/bundle-exec.1.html): `bundle exec sass`.
|
160 |
|
161 |
|
162 | #### update
|
163 |
|
164 | Type: `Boolean`
|
165 | Default: `false`
|
166 |
|
167 | Only compile changed files.
|
168 |
|
169 | ### Examples
|
170 |
|
171 | #### Example config
|
172 |
|
173 | ```javascript
|
174 | grunt.initConfig({
|
175 | sass: { // Task
|
176 | dist: { // Target
|
177 | options: { // Target options
|
178 | style: 'expanded'
|
179 | },
|
180 | files: { // Dictionary of files
|
181 | 'main.css': 'main.scss', // 'destination': 'source'
|
182 | 'widgets.css': 'widgets.scss'
|
183 | }
|
184 | }
|
185 | }
|
186 | });
|
187 |
|
188 | grunt.loadNpmTasks('grunt-contrib-sass');
|
189 |
|
190 | grunt.registerTask('default', ['sass']);
|
191 | ```
|
192 |
|
193 | #### Compile
|
194 |
|
195 | ```javascript
|
196 | grunt.initConfig({
|
197 | sass: {
|
198 | dist: {
|
199 | files: {
|
200 | 'main.css': 'main.scss'
|
201 | }
|
202 | }
|
203 | }
|
204 | });
|
205 | ```
|
206 |
|
207 | #### Concat and compile
|
208 |
|
209 | Instead of concatenating the files, just `@import` them into another `.sass` file eg. `main.scss`.
|
210 |
|
211 |
|
212 | #### Compile multiple files
|
213 |
|
214 | You can specify multiple `destination: source` items in `files`.
|
215 |
|
216 | ```javascript
|
217 | grunt.initConfig({
|
218 | sass: {
|
219 | dist: {
|
220 | files: {
|
221 | 'main.css': 'main.scss',
|
222 | 'widgets.css': 'widgets.scss'
|
223 | }
|
224 | }
|
225 | }
|
226 | });
|
227 | ```
|
228 |
|
229 | #### Compile files in a directory
|
230 |
|
231 | 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`.
|
232 |
|
233 | ```javascript
|
234 | grunt.initConfig({
|
235 | sass: {
|
236 | dist: {
|
237 | files: [{
|
238 | expand: true,
|
239 | cwd: 'styles',
|
240 | src: ['*.scss'],
|
241 | dest: '../public',
|
242 | ext: '.css'
|
243 | }]
|
244 | }
|
245 | }
|
246 | });
|
247 | ```
|
248 |
|
249 |
|
250 | ## Release History
|
251 |
|
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 Sat Feb 07 2015 22:50:05.*
|