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

http://github.com/scalate/scalate · Markdown · 210 lines · 160 code · 50 blank · 0 comment · 0 complexity · 09236832f4355bb20d3a18a819f5d53b MD5 · raw file

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