Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

292 lines (219 sloc) 9.032 kb
title class side_content
Getting Started
guide

Installation

Compass

Install from the command line:

:::bash
# command line
sudo gem install susy --pre

Create a new Compass project:

:::bash
# command line
compass create <project name> -r susy -u susy

Or update an existing Compass project:

:::ruby
# config.rb
require "susy"

Rails 3.x

:::ruby
# Gemfile
gem "susy"

You may also need:

:::ruby
# Gemfile
gem 'compass', '>= 0.12.2'
gem 'compass-rails', '>= 1.0.3'

And run:

:::bash
# command line
bundle install

Usage

:::scss
@import "susy";

Settings

Set up your default grid values: total columns, column width, and gutter width.

:::scss
$total-columns  : 12;             // a 12-column grid
$column-width   : 4em;            // each column is 4em wide
$gutter-width   : 1em;            // 1em gutters between columns
$grid-padding   : $gutter-width;  // grid-padding equal to gutters

Basic Grids

The basic Susy grid is composed using two simple mixins:

  • Use the container() mixin to create your initial grid context.
  • Use the span-columns() mixin to declare the width of an element on the grid.

Here's a simple page layout:

:::scss
.page {
  // page acts as a container for our grid.
  @include container;

  // header and footer are full-width by default.
  header, footer { clear: both; }

  // nav spans 3 columns of total 12.
  nav { @include span-columns(3,12); }

  .content {
    // content spans the final (omega) 9 columns of 12.
    @include span-columns(9 omega,12);

    // main content spans 6 of those 9 columns.
    .main { @include span-columns(6,9); }

    // secondary content spans the final 3 (omega) of 9 columns.
    .secondary { @include span-columns(3 omega,9); }
  }
}

Responsive Grids

Responsive Susy grids allow you to change the number of columns in a layout at different window sizes, using @media-queries with min and max widths. This requires one more mixin:

  • Use at-breakpoint() to set different layouts at min- and max-width breakpoints.

Here's a mobile-first example:

:::scss
$total-columns: 4;

.page {
  // Establish our default 4-column grid container.
  @include container;

  // Create a media-query breakpoint at a min-width of 30em
  // And use a larger 8-column grid within that media-query.
  @include at-breakpoint(30em 8) {
    // Establish our new 8-column container.
    @include container;
  }
}

Advanced

Susy is built to handle your unique markup, and any number of edge cases. It includes the standard push() and pull() mixins, along with other useful functions and shortcuts, support for various grid styles, and even bi-directional grids for multi-lingual sites. Check the reference documentation for details.

Troubleshooting

Version Management

When you are working with bundled gems and dependencies across a number of different projects, managing gem versions can become an issue.

If you are working in a Ruby environment, we recommend using RVM. See our Rails troubleshooting below for some basic instructions, or dig into RVM's installation instructions.

In a Python environment, we recommend virtualenv in conjunction with these "postactivate" and "predeactivate" scripts to add support for Ruby gems.

Once you have that in place, Bundler can be used in either environment to manage the actual installation and updating of the gems.

Compass Install

The old gem and the new gem have different names, but are required simply as susy. That can cause a conflict if both gems are present.

If you have installed Susy in the past, make sure you've uninstalled older versions:

:::bash
# command line
gem uninstall compass-susy-plugin
# "compass-susy-plugin" was the gem name for 0.9.x and lower
# Susy 1.0 switches to "susy" as the gem name

And then install 1.0:

:::bash
# command line
gem install susy

Then use Compass as normal.

CodeKit Install

CodeKit has its own built-in Sass and Compass builds, which it uses in place of the versions you install.

This solution from Gabriel Luethje seems to work in most cases. It involves opening the CodeKit app contents and changing the files within. Proceed at your own risk.

  1. Install the correct Susy, Sass, and Compass gems on your machine.
  2. Close CodeKit.
  3. Make a copy of CodeKit app, just in case.
  4. Right click on the CodeKit file and choose "Show Package Contents".
  5. Navigate to Contents/Resources/engines/.
  6. You will see a compass folder and an scss folder.
  7. Copy the contents of the Sass and Compass files from your install into these folders. (on my machine: /Library/Ruby/Gems/1.8/gems/compass-0.12.2 and /sass-3.2.0)
  8. Match the contents of these folders with the contents of the corresponding folders inside CodeKit app and copy them over. There may be a few extra items in the machine's install.
  9. Restart CodeKit.

Note: Your milage may vary. Updates to the CodeKit app will likely overwrite these modifications.

Rails 3.x Install

We recommend you use RVM for using Susy with Rails projects. It has become the standard gem management system for Rails, it's very easy to install and use, and it helps create and manage Gemsets among different developers working on different branches.

Here are some RVM best practices:

If you have installed Susy in the past, make sure you've uninstalled older versions. See Compass Install above.

Install RVM (These are basics, if you do not have Ruby and Rails already installed in your environment, we recommend you use RVM's installation instructions):

:::bash
# command line
# from your system's root:
curl -L get.rvm.io | bash -s stable

Create a gemset for your site:

:::bash
# command line
rvm gemset create fooBar

Create an .rvmrc file at your site's root:

:::bash
# .rvmrc
rvm use 1.9.3@fooBar
# Use whatever Ruby version number your app uses

Now whenever you cd into your site's root, RVM will pick up and use that Gemset.

cd to your site and install Bundler:

:::bash
# command line
gem install bundler

Add Susy to your Gemfile (more info on Gemfiles):

:::ruby
gem "susy", "~> 1.0.rc.4"

And finally run your bundle:

:::bash
# command line
bundle
Jump to Line
Something went wrong with that request. Please try again.