Skip to content

Getting Started

Jump to bottom Edit New page
mrajcok edited this page Sep 13, 2010 · 66 revisions

Please read the Compass Primer (but don’t follow the installation instructions on that page, and don’t use the HTML — they are out of date) and then come back here. The Primer walks you through some basic editing tasks in a stand alone environment.

Important Note

Compass is using some very new features of Sass. You must install haml 2.2 or later to run Compass.

Install Dependencies

  1. Ruby – How to install Ruby is outside the scope of this document. But it’s really easy so don’t let not having it deter you.
  2. Sass – Sass is part of the Ruby-based project called Haml. Haml/Sass will be installed as a dependency of compass automatically during the next step.
  3. RubyGems – You need to have a fairly recent version of rubygems installed. Please upgrade to 1.3 or greater: sudo gem update --system

Install Compass

sudo gem install compass

Updating Compass to the latest version

If you’ve already installed compass previously, this will update compass for you.

sudo gem update compass

Create your Project

If you’re using one of the following application technologies please read the respective pages (sorted alphabetically):

If you’re using compass stand-alone:

compass -f blueprint project-name
cd project-name

Sass files are in the src directory — edit these.
CSS files are in the stylesheets directory — <link ...> these.

The blueprint framework files that screen.sass @imports are stored under your Ruby gems repository – someplace like /usr/local/lib/ruby/gems/1.9.1/gems/compass-0.8.17/frameworks/blueprint. Similar files exist for the other built-in frameworks, such as YUI and Compass.

Automatic Recompiles

Compass can watch your project and automatically recompile files when it notices changes:

compass -w

A manual recompile is also possible:

compass -u

Your First HTML File

Below is a sample index.html file that does not use any blueprint presentational class names (like span-4).
If your project directory is in the document root directory of your web server, change
<link href="stylesheets... to
<link href="/stylesheets...

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html lang="en">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  <title>Blueprint test page</title>
  <!-- Framework CSS -->
  <link href="stylesheets/screen.css" media="screen, projection" rel="stylesheet" type="text/css">
  <link href="stylesheets/print.css" media="print" rel="stylesheet" type="text/css">
  <!--[if lt IE 8]>
    <link href="stylesheets/ie.css" media="screen, projection" rel="stylesheet" type="text/css">
  <![endif]-->
</head>
<body class="bp three-col">
  <div id="container">
    <div id="header">Header -------------------------</div>
    <div id="sidebar">Sidebar
    	<ul><li>one</li><li>two</li></ul>
    </div>
      <div id="content">
        <h1>Welcome to Compass!</h1>
        This is the main content.
      </div>
    <div id="footer">Footer ----------------------------</div>
  </div>
</body>
</html>

If you want to use the blueprint CSS presentational class names (e.g., to aid with porting some existing blueprint stylesheets), uncomment the “+blueprint” line in screen.sass:

  // To generate css equivalent to the blueprint css but with your configuration applied, uncomment:
  +blueprint

and then delete the remaining lines underneath it.

Learn Sass

If you don’t yet know Sass, please take the time to read through the documentation.

Syntax Highlighting

A complete list of Syntax Highlighting tools (old link) for Sass.

If you use TextMate, I recommend the Bundle by SeaOfClouds

Compass Source Code

Also note that you may find it bewildering to get started without reading the Compass source code. Reading the source code will help you understand

  • Some of the included frameworks
  • Template code for each framework
  • Which mixins are available for you to use for a given framework
  • What each mixin does in CSS.

Check the source out someplace memorable:


cd ~/Desktop
git clone git://github.com/chriseppstein/compass.git

or if you don’t have access to git, this will take you to the source code that was installed via rubygems.


cd `compass --install-dir`
Add a custom footer
Add a custom sidebar
Clone this wiki locally