/scalate-jruby/src/main/resources/haml-3.0.25/doc-src/SCSS_FOR_SASS_USERS.md

  1# Intro to SCSS for Sass Users
  2
  3Sass 3 introduces a new syntax known as SCSS
  4which is fully compatible with the syntax of CSS3,
  5while still supporting the full power of Sass.
  6This means that every valid CSS3 stylesheet
  7is a valid SCSS file with the same meaning.
  8In addition, SCSS understands most CSS hacks
  9and vendor-specific syntax, such as [IE's old `filter` syntax](http://msdn.microsoft.com/en-us/library/ms533754%28VS.85%29.aspx).
 10
 11Since SCSS is a CSS extension,
 12everything that works in CSS works in SCSS.
 13This means that for a Sass user to understand it,
 14they need only understand how the Sass extensions work.
 15Most of these, such as variables, parent references, and directives work the same;
 16the only difference is that SCSS requires semicolons
 17and brackets instead of newlines and indentation.
 18For example, a simple rule in Sass:
 19
 20    #sidebar
 21      width: 30%
 22      background-color: #faa
 23
 24could be converted to SCSS just by adding brackets and semicolons:
 25
 26    #sidebar {
 27      width: 30%;
 28      background-color: #faa;
 29    }
 30
 31In addition, SCSS is completely whitespace-insensitive.
 32That means the above could also be written as:
 33
 34    #sidebar {width: 30%; background-color: #faa}
 35
 36There are some differences that are slightly more complicated.
 37These are detailed below.
 38Note, though, that SCSS uses all the
 39{file:SASS_CHANGELOG.md#3-0-0-syntax-changes syntax changes in Sass 3},
 40so make sure you understand those before going forward.
 41
 42## Nested Selectors
 43
 44To nest selectors, simply define a new ruleset
 45inside an existing ruleset:
 46
 47    #sidebar {
 48      a { text-decoration: none; }
 49    }
 50
 51Of course, white space is insignificant
 52and the last trailing semicolon is optional
 53so you can also do it like this:
 54
 55    #sidebar { a { text-decoration: none } }
 56
 57## Nested Properties
 58
 59To nest properties,
 60simply create a new property set
 61after an existing property's colon:
 62
 63    #footer {
 64      border: {
 65        width: 1px;
 66        color: #ccc;
 67        style: solid;
 68      }
 69    }
 70
 71This compiles to:
 72
 73    #footer {
 74      border-width: 1px;
 75      border-color: #cccccc;
 76      border-style: solid; }
 77
 78## Mixins
 79
 80A mixin is declared with the `@mixin` directive:
 81
 82    @mixin rounded($amount) {
 83      -moz-border-radius: $amount;
 84      -webkit-border-radius: $amount;
 85      border-radius: $amount;
 86    }
 87
 88A mixin is used with the `@include` directive:
 89
 90    .box {
 91      border: 3px solid #777;
 92      @include rounded(0.5em);
 93    }
 94
 95This syntax is also available in the indented syntax,
 96although the old `=` and `+` syntax still works.
 97
 98This is rather verbose compared to the `=` and `+` characters used in Sass syntax.
 99This is because the SCSS format is designed for CSS compatibility rather than conciseness,
100and creating new syntax when the CSS directive syntax already exists
101adds new syntax needlessly and
102could create incompatibilities with future versions of CSS.
103
104## Comments
105
106Like Sass, SCSS supports both comments that are preserved in the CSS output
107and comments that aren't.
108However, SCSS's comments are significantly more flexible.
109It supports standard multiline CSS comments with `/* */`,
110which are preserved where possible in the output.
111These comments can have whatever formatting you like;
112Sass will do its best to format them nicely.
113
114SCSS also uses `//` for comments that are thrown away, like Sass.
115Unlike Sass, though, `//` comments in SCSS may appear anywhere
116and last only until the end of the line.
117
118For example:
119
120    /* This comment is
121     * several lines long.
122     * since it uses the CSS comment syntax,
123     * it will appear in the CSS output. */
124    body { color: black; }
125
126    // These comments are only one line long each.
127    // They won't appear in the CSS output,
128    // since they use the single-line comment syntax.
129    a { color: green; }
130
131is compiled to:
132
133    /* This comment is
134     * several lines long.
135     * since it uses the CSS comment syntax,
136     * it will appear in the CSS output. */
137    body {
138      color: black; }
139
140    a {
141      color: green; }
142
143## `@import`
144
145The `@import` directive in SCSS functions just like that in Sass,
146except that it takes a quoted string to import.
147For example, this Sass:
148
149    @import themes/dark
150    @import font.sass
151
152would be this SCSS:
153
154    @import "themes/dark";
155    @import "font.sass";