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.*
|