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

  1# Sass Indented Syntax
  2
  3* Table of contents
  4{:toc}
  5
  6Sass's indented syntax (also known simply as "Sass")
  7is designed to provide a more concise
  8and, for some, more aesthetically appealing alternative
  9to the CSS-based SCSS syntax.
 10It's not compatible with CSS;
 11instead of using `{` and `}` to delimit blocks of styles,
 12it uses indentation,
 13and instead of using semicolons to separate statements it uses newlines.
 14This usually leads to substantially less text
 15when saying the same thing.
 16
 17Each statement in Sass, such as property declarations and selectors,
 18must be placed on its own line.
 19In addition, everything that would be within `{` and `}` after a statement
 20must be on a new line and indented one level deeper than that statement.
 21For example, this CSS:
 22
 23    #main {
 24      color: blue;
 25      font-size: 0.3em;
 26    }
 27
 28would be this Sass:
 29
 30    #main
 31      color: blue
 32      font-size: 0.3em
 33
 34Similarly, this SCSS:
 35
 36    #main {
 37      color: blue;
 38      font-size: 0.3em;
 39
 40      a {
 41        font: {
 42          weight: bold;
 43          family: serif;
 44        }
 45        &:hover {
 46          background-color: #eee;
 47        }
 48      }
 49    }
 50
 51would be this Sass:
 52
 53    #main
 54      color: blue
 55      font-size: 0.3em
 56
 57      a
 58        font:
 59          weight: bold
 60          family: serif
 61        &:hover
 62          background-color: #eee
 63
 64## Sass Syntax Differences
 65
 66In general, most CSS and SCSS syntax
 67works straightforwardly in Sass
 68by using newlines instead of semicolons
 69and indentation instead of braces.
 70However, there are some cases where there are differences or subtleties,
 71which are detailed below.
 72
 73## Property Synax
 74
 75The indented syntax supports two ways of declaring CSS properties.
 76The first is just like CSS, except without the semicolon.
 77The second, however, places the colon *before* the property name.
 78For example:
 79
 80    #main
 81      :color blue
 82      :font-size 0.3em
 83
 84By default, both ways may be used.
 85However, the {file:SASS_REFERENCE.md#property_syntax-option `:property_syntax` option}
 86may be used to specify that only one property syntax is allowed.
 87
 88### Multiline Selectors
 89
 90Normally in the indented syntax, a single selector must take up a single line.
 91There is one exception, however:
 92selectors can contain newlines as long as they only appear after commas.
 93For example:
 94
 95    .users #userTab,
 96    .posts #postTab
 97      width: 100px
 98      height: 30px
 99
100### Comments
101
102Like everything else in the indented syntax,
103comments are line-based.
104This means that they don't work the same way as in SCSS.
105They must take up an entire line,
106and they also encompass all text nested beneath them.
107
108Like SCSS, the indented syntax supports two kinds of comments.
109Comments beginning with `/*` are preserved in the CSS output,
110although unlike SCSS they don't require a closing `*/`.
111Comments beginning with `//` are removed entirely.
112For example:
113
114    /* This comment will appear in the CSS output.
115      This is nested beneath the comment,
116      so it's part of it
117    body
118      color: black
119
120    // This comment will not appear in the CSS output.
121      This is nested beneath the comment as well,
122      so it also won't appear
123    a
124      color: green
125
126is compiled to:
127
128    /* This comment will appear in the CSS output.
129     * This is nested beneath the comment,
130     * so it's part of it */
131    body {
132      color: black; }
133
134    a {
135      color: green; }
136
137### `@import`
138
139The `@import` directive in Sass does not require quotes, although they may be used.
140For example, this SCSS:
141
142    @import "themes/dark";
143    @import "font.sass";
144
145would be this Sass:
146
147    @import themes/dark
148    @import font.sass
149
150### Mixin Directives
151
152Sass supports shorthands for the `@mixin` and `@include` directives.
153Instead of writing `@mixin`, you can use the character `=`;
154instead of writing `@include`, you can use the character `+`.
155For example:
156
157    =large-text
158      font:
159        family: Arial
160        size: 20px
161        weight: bold
162      color: #ff0000
163
164    h1
165      +large-text
166
167is the same as:
168
169    @mixin large-text
170      font:
171        family: Arial
172        size: 20px
173        weight: bold
174      color: #ff0000
175
176    h1
177      @include large-text
178
179## Deprecated Syntax
180
181Since the indented syntax has been around for a while,
182previous versions have made some syntactic decisions
183that have since been changed.
184Some of the old syntax still works, though,
185so it's documented here.
186
187**Note that this syntax is not recommended
188for use in new Sass files**.
189It will print a warning if it's used,
190and it will be removed in a future version.
191
192### `=` for Properties and Variables
193
194`=` used to be used instead of `:` when setting variables
195and when setting properties to SassScript values.
196It has slightly different semantics than `:`;
197see {file:SASS_CHANGELOG.md#3-0-0-sass-script-context this changelog entry} for details.
198
199### `||=` for Default Variables
200
201`||=` used to be used instead of `:` when setting the default value of a variable.
202The `!default` flag was not used.
203The variable value has the same semantics as `=`;
204see {file:SASS_CHANGELOG.md#3-0-0-sass-script-context this changelog entry} for details.
205
206### `!` Prefix for Variables
207
208`!` used to be used as the variable prefix instead of `$`.
209This had no difference in functionality;
210it was a purely aesthetic change.