A primer coat for a SASS project based on the original Gesso CSS project. Compass-Gesso configures a new SASS project to use Compass and Susy and sets up a number of variables and mixins for use throughout.
These instructions are for users running Apple Mac OS X. They will work on Linux as well, although, some additional work may be required (for example, ruby and rubygems may need to be installed).
Installing Compass and Susy
You must have Ruby installed (Apple's Mac OS X ships with Ruby installed). Advanced users may want to use RVM or some other version of Gem management. The following command uses rubygems to install compass and susy onto your system. Launch a Terminal window (located in the Utilities folder of your Applications folder on Mac OS X (you can also search for it with Spotlight) and copy in everything after the
$ (that's just a documentation reference to indicate that it is a command to be executed in the Terminal). Press return on your keyboard to execute.
Those new to the Terminal are encouraged to read The Designer's Guide to the OSX Command Prompt
$ gem install compass susy
Create a new Compass project using the SASS syntax and requiring the Susy plugin.
In the root of your project (next to index.html or index.php in a LAMP stack; a quick shortcut to open your Terminal window to this folder is to drag the folder from Apple's Finder window into your Terminal window and press enter. For example if you are using your User's Sites folder drag the Sites folder into a new Terminal window and press return. Alternately, use
$ cd to change directory to the appropriate file, for example if you are using your User's Sites folder type
$ cd ~/sites before running the following command) run:
$ compass create stylesheets --syntax sass -r susy -u susy
Because you can't create a bare project when including a requirement, remove the default base and screen SASS files.
$ rm stylesheets/sass/_base.sass stylesheets/sass/screen.sass
Clone this project into the sass directory.
$ git clone https://github.com/jbergantine/compass-gesso/ stylesheets/sass/.
Reference the compiled CSS files in the
<head> of your document.
<link rel="stylesheet" href="/stylesheets/stylesheets/screen.css" media="screen" /> <link rel="stylesheet" href="/stylesheets/stylesheets/print.css" media="print" />
CSS files will be created in stylesheets/stylesheets the first time you run either
$ compass watch stylesheets or
$ compass compile stylesheets.
If you are using Git for version control of your project it is highly recommended that you do not include the .sass-cache directory or compiled CSS files as part of the project. Add the following rules to your .gitignore file to do this:
Note that excluding the CSS files will require you to compile the SASS files after pulling in changes or deploying.
You can create a post-merge Git hook locally to compile stylesheets any time you run a pull request that brings in changes:
$ touch .git/hooks/post-merge $ echo "#\!/bin/sh\ncompass compile stylesheets -e production --force" >> .git/hooks/post-merge $ chmod u+x .git/hooks/post-merge
Now any time you run
$ git pull ... (and the remote repo is different than your local repo; if there are no changes, there is no Git merge and the post-merge hook will not execute) compass will compile stylesheets.
You can create a Git hook for production as well depending on your deployment method.
This is where mixins and variables are defined. This also imports compass to the project as well as the Susy responsive grid.
The main stylesheet. This imports
\_base.sass, calls a reset and begins defining the styles for elements, classes and ids.
A stylesheet specifically for print styling.
- In print.sass, replace
siteURL.comwith the site's domain name.
Compass Command Tips
Create a New Compass Project with SASS Syntax
SASS is cleaner than SCSS as it requires indentation only and no braces or semicolons.
$ compass create <path_to_compass_proejct> --syntax sass
For example, if you want your compass project to be named stylesheets and your website looks like this:
- sites |- index.html |- images |- ...
Run, from the sites directory:
$ compass create stylesheets --syntax sass
Which will create the compass project at sites/stylesheets.
If you prefer SCSS syntax you can do that too:
$ compass create <path_to_compass_project> --syntax scss
You'll have to convert this project's SASS files to SCSS files if you do that. To do so run:
$ sass-convert --from sass2 --to scss --recursive <path_to_compass_project>
It is recommended, if you prefer to use SCSS, that you create the project using SCSS syntax rather than creating a project using SASS syntax and changing midstream. If you convert midstream, you will additionally have to edit the config.rb file within the Compass project to indicate that you wish to use SCSS rather than SASS syntax to avoid compilation errors. Open that file in a text editor and replace
preferred_syntax = :sass with
preferred_syntax = :scss. Save and quit before recompiling.
Watch SASS files for changes and recompile CSS
Automatically recompiles CSS when you save changes to a SASS file. Use for development.
$ compass watch <path_to_compass_project>
If your website is setup like this:
- sites |- index.html |- stylesheets |- sass |- screen.sass |- ... |- stylesheets |- screen.css |- ... |- ...
Run, from the sites directory:
$ compass watch stylesheets
Compile Stylesheets for Production
This sucks all the whitespace out, greatly reducing file size
$ compass compile <path_to_compass_project> -e production --force
More information is available in the Compass Command Line documentation.