/ Web Design & Development

A Brief Description of SASS to CSS Compiling and Mapping

Araf Nishan

Read more posts by this author.

Read More
A Brief Description of SASS to CSS Compiling and Mapping

Sass (Syntactically Awesome Stylesheets) is an extension of CSS that adds power and elegance to the basic language. It allows you to use variables, nested rules, mixins, inline imports, and more, all with a fully CSS-compatible syntax. Sass helps keep large stylesheets well-organized, and get small stylesheets up and running quickly, particularly with the help of the Compass style library.


  • Fully CSS-compatible
  • Language extensions such as variables, nesting, and mixins
  • Many useful functions for manipulating colors and other values
  • Advanced features like control directives for libraries
  • Well-formatted, customizable output


There are two syntaxes available for Sass. The first, known as SCSS (Sassy CSS) and used throughout this reference, is an extension of the syntax of CSS. This means that every valid CSS stylesheet is a valid SCSS file with the same meaning.

In addition, SCSS understands most CSS hacks and vendor-specific syntax, such as IE's old filter syntax. This syntax is enhanced with the Sass features described below. Files using this syntax have the .scss extension.

The second and older syntax, known as the indented syntax (or sometimes just "Sass"), provides a more concise way of writing CSS. It uses indentation rather than brackets to indicate nesting of selectors, and newlines rather than semicolons to separate properties.

Some people find this to be easier to read and quicker to write than SCSS. The indented syntax has all the same features, although some of them have slightly different syntax; this is described in the indented syntax reference. Files using this syntax have the .sass extension.

Either syntax can import files written in the other. Files can be automatically converted from one syntax to the other using the sass-convert command line tool:

# Convert Sass to SCSS

$ sass-convert style.sass style.scss

# Convert SCSS to Sass

$ sass-convert style.scss style.sass

Note that this command does not generate CSS files. For that, use the sass command described elsewhere.

Using Sass

Sass can be used in three ways: as a command-line tool, as a standalone Ruby module, and as a plugin for any Rack-enabled framework, including Ruby on Rails and Merb. The first step for all of these is to install the Sass gem:

gem install sass

If you're using Windows, you may need to install Ruby first.

To run Sass from the command line, just use

sass input.scss output.css

You can also tell Sass to watch the file and update the CSS every time the Sass file changes:

sass --watch input.scss:output.css

If you have a directory with many Sass files, you can also tell Sass to watch the entire directory:

sass --watch app/sass:public/stylesheets

Use sass --help for full documentation.

Using Sass in Ruby code is very simple. After installing the Sass gem, you can use it by running require "sass" and using Sass::Engine like so:

engine = Sass::Engine.new("#main {background-color: #0000ff}", :syntax => :scss)

engine.render #=> "#main { background-color: #0000ff; }\n"

Rack/Rails/Merb Plugin

To enable Sass in Rails versions before Rails 3, add the following line to environment.rb:

config.gem "sass"

For Rails 3, instead add the following line to the Gemfile:

gem "sass"

To enable Sass in Merb, add the following line to config/dependencies.rb:

dependency "merb-haml"

To enable Sass in a Rack application, add the following lines to config.ru.

require 'sass/plugin/rack'

use Sass::Plugin::Rack

Sass stylesheets don't work the same as views. They don't contain dynamic content, so the CSS only needs to be generated when the Sass file has been updated. By default, .sass and .scss files are placed in public/stylesheets/sass (this can be customized with the :template_locationoption). Then, whenever necessary, they're compiled into corresponding CSS files in public/stylesheets. For instance, public/stylesheets/sass/main.scss would be compiled to public/stylesheets/main.css.


By default, Sass caches compiled templates and partials. This dramatically speeds up re-compilation of large collections of Sass files, and works best if the Sass templates are split up into separate files that are all @imported into one large file.

Without a framework, Sass puts the cached templates in the .sass-cache directory. In Rails and Merb, they go in tmp/sass-cache. The directory can be customized with the :cache_location option. If you don't want Sass to use caching at all, set the :cache option to false.


Options can be set by setting the Sass::Plugin#options hash in environment.rb in Rails or config.ru in Rack...

Sass::Plugin.options[:style] = :compact

...or by setting the Merb::Plugin.config[:sass] hash in init.rb in Merb...

Merb::Plugin.config[:sass][:style] = :compact

...or by passing an options hash to Sass::Engine#initialize. All relevant options are also available via flags to the sass and scss command-line executables. Available options are:

  • :style: Sets the style of the CSS output. See Output Style.
  • :syntax: The syntax of the input file, :sass for the indented syntax and :scss for the CSS-extension syntax. This is only useful when you're constructing Sass::Engine instances yourself; it's automatically set properly when using Sass::Plugin. Defaults to :sass.
  • :property_syntax: Forces indented-syntax documents to use one syntax for properties. If the correct syntax isn't used, an error is thrown. :new forces the use of a colon after the property name. For example: color: #0f3 or width: $main_width. :old forces the use of a colon before the property name. For example: :color #0f3 or :width $main_width. By default, either syntax is valid. This has no effect on SCSS documents.
  • :cache: Whether parsed Sass files should be cached, allowing greater speed. Defaults to true.
  • :read_cache: If this is set and :cache is not, only read the Sass cache if it exists, don't write to it if it doesn't.
  • :cache_store: If this is set to an instance of a subclass of Sass::CacheStores::Base, that cache store will be used to store and retrieve cached compilation results. Defaults to a Sass::CacheStores::Filesystem that is initialized using the :cache_location option.
  • :never_update: Whether the CSS files should never be updated, even if the template file changes. Setting this to true may give small performance gains. It always defaults to false. Only has meaning within Rack, Ruby on Rails, or Merb.
  • :always_update: Whether the CSS files should be updated every time a controller is accessed, as opposed to only when the template has been modified. Defaults to false. Only has meaning within Rack, Ruby on Rails, or Merb.
  • :always_check: Whether a Sass template should be checked for updates every time a controller is accessed, as opposed to only when the server starts. If a Sass template has been updated, it will be recompiled and will overwrite the corresponding CSS file. Defaults to false in production mode, true otherwise. Only has meaning within Rack, Ruby on Rails, or Merb.
  • :poll: When true, always use the polling backend for Sass::Plugin::Compiler#watch rather than the native filesystem backend.
  • :full_exception: Whether an error in the Sass code should cause Sass to provide a detailed description within the generated CSS file. If set to true, the error will be displayed along with a line number and source snippet both as a comment in the CSS file and at the top of the page (in supported browsers). Otherwise, an exception will be raised in the Ruby code. Defaults to false in production mode, true otherwise.
  • :template_location: A path to the root sass template directory for your application. If a hash, :css_location is ignored and this option designates a mapping between input and output directories. May also be given a list of 2-element lists, instead of a hash. Defaults to css_location + "/sass". Only has meaning within Rack, Ruby on Rails, or Merb. Note that if multiple template locations are specified, all of them are placed in the import path, allowing you to import between them. Note that due to the many possible formats it can take, this option should only be set directly, not accessed or modified. Use the Sass::Plugin#template_location_array, Sass::Plugin#add_template_location, and Sass::Plugin#remove_template_location methods instead.
  • :css_location: The path where CSS output should be written to. This option is ignored when :template_location is a Hash. Defaults to "./public/stylesheets". Only has meaning within Rack, Ruby on Rails, or Merb.
  • :cache_location: The path where the cached sassc files should be written to. Defaults to "./tmp/sass-cache" in Rails and Merb, or "./.sass-cache" otherwise. If the :cache_store option is set, this is ignored.
  • :unix_newlines: If true, use Unix-style newlines when writing files. Only has meaning on Windows, and only when Sass is writing the files (in Rack, Rails, or Merb, when using Sass::Plugindirectly, or when using the command-line executable).
  • :filename: The filename of the file being rendered. This is used solely for reporting errors, and is automatically set when using Rack, Rails, or Merb.
  • :line: The number of the first line of the Sass template. Used for reporting line numbers for errors. This is useful to set if the Sass template is embedded in a Ruby file.
  • :load_paths: An array of filesystem paths or importers which should be searched for Sass templates imported with the @import directive. These may be strings, Pathname objects, or subclasses of Sass::Importers::Base. This defaults to the working directory and, in Rack, Rails, or Merb, whatever :template_location is. The load path is also informed by Sass.load_pathsand the SASS_PATH environment variable.
  • :filesystem_importer: A Sass::Importers::Base subclass used to handle plain string load paths. This should import files from the filesystem. It should be a Class object inheriting from Sass::Importers::Base with a constructor that takes a single string argument (the load path). Defaults to Sass::Importers::Filesystem.
  • :sourcemap: Controls how sourcemaps are generated. These sourcemaps tell the browser how to find the Sass styles that caused each CSS style to be generated. This has three valid values: :auto uses relative URIs where possible, assuming that that the source stylesheets will be made available on whatever server you're using, and that their relative location will be the same as it is on the local filesystem. If a relative URI is unavailable, a "file:" URI is used instead. :file always uses "file:" URIs, which will work locally but can't be deployed to a remote server. :inlineincludes the full source text in the sourcemap, which is maximally portable but can create very large sourcemap files. Finally, :none causes no sourcemaps to be generated at all.
  • :line_numbers: When set to true, causes the line number and file where a selector is defined to be emitted into the compiled CSS as a comment. Useful for debugging, especially when using imports and mixins. This option may also be called :line_comments. Automatically disabled when using the :compressed output style or the :debug_info/:trace_selectors options.
  • :trace_selectors: When set to true, emit a full trace of imports and mixins before each selector. This can be helpful for in-browser debugging of stylesheet imports and mixin includes. This option supersedes the :line_comments option and is superseded by the :debug_info option. Automatically disabled when using the :compressed output style.
  • :debug_info: When set to true, causes the line number and file where a selector is defined to be emitted into the compiled CSS in a format that can be understood by the browser. Useful in conjunction with the FireSass Firebug extension for displaying the Sass filename and line number. Automatically disabled when using the :compressed output style.
  • :custom: An option that's available for individual applications to set to make data available to custom Sass functions.
  • :quiet: When set to true, causes warnings to be disabled.

Syntax Selection

The Sass command-line tool will use the file extension to determine which syntax you are using, but there's not always a filename. The sass command-line program defaults to the indented syntax but you can pass the --scss option to it if the input should be interpreted as SCSS syntax. Alternatively, you can use the scss command-line program which is exactly like the sassprogram but it defaults to assuming the syntax is SCSS.


When running on Ruby 1.9 and later, Sass is aware of the character encoding of documents. Sass follows the CSS spec to determine the encoding of a stylesheet, and falls back to the Ruby string encoding. This means that it first checks the Unicode byte order mark, then the @charset declaration, then the Ruby string encoding. If none of these are set, it will assume the document is in UTF-8.

To explicitly specify the encoding of your stylesheet, use a @charset declaration just like in CSS. Add @charset "encoding-name"; at the beginning of the stylesheet (before any whitespace or comments) and Sass will interpret it as the given encoding. Note that whatever encoding you use, it must be convertible to Unicode.

Sass will always encode its output as UTF-8. It will include a @charset declaration if and only if the output file contains non-ASCII characters. In compressed mode, a UTF-8 byte order mark is used in place of a @charset declaration.

CSS Extensions

Nested Rules

Sass allows CSS rules to be nested within one another. The inner rule then only applies within the outer rule's selector. For example:

#main p {

color: #00ff00;

width: 97%;

.redbox {

background-color: #ff0000;

color: #000000;


is compiled to:

#main p {

color: #00ff00;

width: 97%; }

#main p .redbox {

background-color: #ff0000;

color: #000000; }

This helps avoid repetition of parent selectors, and makes complex CSS layouts with lots of nested selectors much simpler. For example:

#main {

width: 97%;

p, div {

font-size: 2em;

a { font-weight: bold; }

pre { font-size: 3em; }


is compiled to:

#main {

width: 97%; }

#main p, #main div {

font-size: 2em; }

#main p a, #main div a {

font-weight: bold; }

#main pre {

font-size: 3em; }

Referencing Parent Selectors: &

Sometimes it's useful to use a nested rule's parent selector in other ways than the default. For instance, you might want to have special styles for when that selector is hovered over or for when the body element has a certain class. In these cases, you can explicitly specify where the parent selector should be inserted using the & character. For example:

a {

font-weight: bold;

text-decoration: none;

&:hover { text-decoration: underline; }

body.firefox & { font-weight: normal; }


is compiled to:

a {

font-weight: bold;

text-decoration: none; }

a:hover {

text-decoration: underline; }

body.firefox a {

font-weight: normal; }

& will be replaced with the parent selector as it appears in the CSS. This means that if you have a deeply nested rule, the parent selector will be fully resolved before the & is replaced. For example:

#main {

color: black;

a {

font-weight: bold;

&:hover { color: red; }


is compiled to:

#main {

color: black; }

#main a {

font-weight: bold; }

#main a:hover {

color: red; }

& must appear at the beginning of a compound selector, but it can be followed by a suffix that will be added to the parent selector. For example:

#main {

color: black;

&-sidebar { border: 1px solid; }


is compiled to:

#main {

color: black; }

#main-sidebar {

border: 1px solid; }

If the parent selector can't have a suffix applied, Sass will throw an error.

Nested Properties

CSS has quite a few properties that are in "namespaces;" for instance, font-family, font-size, and font-weight are all in the font namespace. In CSS, if you want to set a bunch of properties in the same namespace, you have to type it out each time. Sass provides a shortcut for this: just write the namespace once, then nest each of the sub-properties within it. For example:

.funky {

font: {

family: fantasy;

size: 30em;

weight: bold;


is compiled to:

.funky {

font-family: fantasy;

font-size: 30em;

font-weight: bold; }

The property namespace itself can also have a value. For example:

.funky {

font: 20px/24px fantasy {

weight: bold;


is compiled to:

.funky {

font: 20px/24px fantasy;

font-weight: bold;


Placeholder Selectors: %foo

Sass supports a special type of selector called a "placeholder selector". These look like class and id selectors, except the # or . is replaced by %. They're meant to be used with the @extenddirective; for more information see @extend-Only Selectors.

On their own, without any use of @extend, rulesets that use placeholder selectors will not be rendered to CSS.

Using source maps with Sass 3.3

One of the exciting new features in Sass 3.3 that every developer should take advantage of is source maps.

As CSS pre-processors, minifiers, and JavaScript transpilers have become mainstream it is increasingly difficult to debug the code running in the browser because of differences with the original source code.

For example, if you use CoffeeScript (which compiles to JavaScript) you won't see CoffeeScript while debugging in the browser. Instead, you'll see compiled JavaScript. The same problem exists for Sass which compiles down to CSS.

Source maps seek to bridge the gap between higher-level languages like CoffeeScript and Sass and the lower-level languages they compile down to (JavaScript and CSS). Source maps allow you to see the original source (the CoffeeScript or Sass) instead of the compiled JavaScript or CSS while debugging.

In practice, for Sass users, this means that when you inspect an element with developer tools, rather than seeing the CSS styles associated with that element, you can see the code we reallycare about: the pre-compiled Sass.

Generating source maps for Sass

To get access to this feature in the browser, you need to generate a source map file for each source file.

For Sass, this is as easy as adding a flag to Sass's command line tool:

$ sass sass/screen.scss:stylesheets/screen.css --sourcemap

If you look in your output folder after running that command, you'll notice that a comment has been added to the end of the generated CSS file:

/*# sourceMappingURL=screen.css.map */

This points to an additional file that was created during compilation: screen.css.map, which - as the name implies - is what maps all of the compiled CSS back to the source Sass declarations. If you're interested in the details of this file and how source maps actually work, check out Ryan Seddon's Introduction to JavaScript Source Maps over at HTML5Rocks. (Even though the article implies that it's only about JavaScript, all source maps work the same.)

Enabling source maps in the browser

The second thing we need to do to take advantage of source maps is to make sure that our browser knows look for them. Chrome, Firefox and Safari all have support for source maps.


If you're using Chrome, source maps are now part of the core feature set, so you don't have to monkey around in chrome://flags any more. Simply open up the DevTools settings and toggle the Enable CSS Source Maps option:

Enabling source maps in Chrome


For Firefox users, source maps are in version 29. You can enable them in the Toolbox Optionsmenu (the gear icon) or by right-clicking anywhere in the Style Inspector's rule view and selecting the Show original sources option. (More info is available at the Mozilla blog.)


Safari is a bit ahead of the curve in terms of source map support. If a map file is detected, references are automatically changed to the source-mapped files, no configuration necessary.

Another Tool in Our Belt

Once source maps are enabled in your browser of choice, the source reference for every style will change from the generated CSS to the source Sass, right down to the line number. Amazing!

Viewing Sass in the developer tools

Just as Firebug and its successors drastically improved our ability to debug in the browser, source maps increase the depth of our diagnostic capabilities. By allowing us to directly access our pre-compiled code, we can find and fix problems faster than ever. Now that I've been using source maps for a few months, I can't imagine working without them.