Hey. Welcome to Derby. Derby is an add-on for Sublime Text 2 that extends the SASS libraries Bourbon and Neat.

So what specifically does Derby do? It autocompletes all Bourbon and Neat statements allowing you to write faster SCSS / SASS. It also has the whole Bourbon and Neat docs compiled into it which can be called with a simple command. This prevents you from having to leave your work to look up certain functions, which for me often means losing focus.

Why the name Derby? Derby is named after a cocktail which is composed of Bourbon, Lime, Vermouth and Orange Curaçao. I like to think of Derby as the Vermouth and the Curaçao in the recipe because it ties the flavors together of Sublime and Bourbon to make a potent drink. While not the main ingredient it makes it smoother and adds some different flavor.

Are You Ready? Well, let's get Derby installed so you can try it.

This package only works with Sublime Text 2 and Bourbon + Neat. The SASS Textmate Bundle is also required as it enables Sublime Text to understand and process the autocompletions.

Derby can also be installed through Package Control, which is a wonderful tool that allows you to install packages right from Sublime Text 2. No more leaving your text editor to find resources.

Install SASS Syntax Bundle

I have found that if you had a previous version of this bundle installed, you have to uninstall and reinstall through Package Control or through the GitHub below.


Install Bourbon & Neat into your project

You may or may not already have the appropraite Ruby Gems installed for both of these libraries. If you are running Codekit, it is easy to install Bourbon. Neat, however, must be installed as Gem still. You will love it though, so don't be intimated.


Clone Derby or Install With Package Control

Clone the Derby repository into your Sublime Text 2 Packages folder, or install through Package Control for Sublime Text 2.


To install through Package Control in Sublime Text 2, type "Command + Shift + P" and type "Install" and select "Install Package". Search for "Derby" or "Bourbon"

Command + Shift P -> "Install Package" -> Search "Derby"

Sublime Text 2

If you are starting from square one and have no clue what Sublime Text 2 or Bourbon/Neat is then consider obtaining both of these great development tools. All instructions from this point on will be geared towards Sublime Text 2 and setting up your workspace

Sublime Text 2 is an advanced text editor for developers. It is well thought out and when used properly can speed up your development and improve your workflow tremendously. It also has the capability of being extended and added to through open source packages ( which is what Derby is ;) winky face! ). You can obtain Sublime Text 2 here.


Bourbon & Neat

So you have Sublime Text 2, but don't know what SASS or Bourbon is? SASS is a preprocessor for CSS that was developed in Ruby. It extends the functionality of CSS immensely and comes highly recommended by many developers. Bourbon is an add-on for SASS that allows you to develop even more rapidly by streamlining common CSS attributes and functions we deal with everyday.

The best part about Bourbon is it has a very small footprint and is non-obtrusive on your stylesheets. It only outputs what you use, which many other add-on libraries cannot lay claim to. Neat is a Bourbon add-on which is specifically only a grid system.


You can also install Bourbon and Neat as Ruby gems

$ gem install bourbon
$ gem install neat

Auto Completion. Type less and do more.

Autocompletions do exactly what their name implies, they automatically complete phrases as you type. This can greatly speed up your workflow and typing speed which over the course of months can save hours and even weeks of production!

To run an autocomplete, type in the property you are looking for and hit Tab. Most of the time you don't have to type the complete term because fuzzy searching in Sublime will catch it. Here is an example with : representing the Tab key.

transition : @include transition ( all 2.0s ease-in-out );

So what happened here? As you type transition a list will drop down that will allow you to select transition and after hitting tab it outputs the code ready for you to type in your properties.

So I am sure you are wondering what autocompletions are included in Derby? The answer is, "All of them!" Here is a list for your convenience that you can reference organized in fancy tabs.

Tab Trigger Property
animation @include animation( scale 1.0s ease-in );
animation-name @include animation-name( scale, slide );
animation-delay @include animation-delay( );
animation-direction @include animation-direction( );
animation-duration @include animation-duration( 0.3s );
animation-fill-mode @include animation-fill-mode( );
animation-iteration-count @include animation-iteration-count( infinite );
animation-name @include animation-name( );
animation-play-state @include animation-play-state( );
animation-play-state @include animation-play-state( );
animation-timing-function @include animation-timing-function( ease );
appearance @include appearance( none );
background @include background( );
background-image @include background-image( );
background-size @include background-size( 50% 100% );
border-image @include border-image(url( /images/border.png ) 27 repeat );
border-radius @include border-radius( );
border-top-radius @include border-top-radius( );
border-top-left-radius @include border-top-left-radius( );
border-top-right-radius @include border-top-right-radius( );
border-bottom-radius @include border-bottom-radius( );
border-bottom-left-radius @include border-bottom-left-radius( );
border-bottom-right-radius @include border-bottom-right-radius( );
border-left-radius @include border-left-radius( );
box-shadow @include box-shadow( 0 0 5px 3px hsla(0, 0%, 0%, 0.65) );
box-sizing @include box-sizing( border-box );
columns @include columns( 12 8em );
column-count @include column-count( );
column-fill @include column-fill( );
column-gap @include column-gap( );
column-rule @include column-rule( );
column-rule-color @include column-rule-color( );
column-rule-style @include column-rule-style( );
column-rule-width @include column-rule-width( );
column-span @include column-span( );
column-width @include column-width( );
flex-box @include flex-box( );
box @include box( );
box-align @include box-align( start | end | center | baseline | stretch );
box-direction @include box-direction( );
box-flex @include box-flex( );
box-flex-group @include box-flex-group( );
box-lines @include box-lines( );
box-ordinal-group @include box-ordinal-group( );
box-orient @include box-orient( );
box-pack @include box-pack( );
display-box @include display-box;
font-face @include font-face( nobile, '/fonts/nobile_italic', normal, italic );
hidpi @include hidpi( 1.5 );
image-rendering @include image-rendering( optimizeSpeed );
keyframes @include keyframes( fadeIn ) { from {@include transform(scale( 0 ) );
linear-gradient @include linear-gradient( #1e5799, #2989d8 );
perspective @include perspective( 300px );
perspective-origin @include perspective-origin( 30% 30% );
placeholder @include placeholder { color: red; }
radial-gradient @include radial-gradient( #1e5799, #3dc3d1 );
transform @include transform( translateY(50px) );
transform-origin @include transform-origin( center top );
transform-style @include transform-style( preserve-3d );
transition @include transition ( all 2.0s ease-in-out );
transition-delay @include transition-delay( );
transition-duration @include transition-duration( );
transition-property @include transition-property( );
transition-timing-function @include transition-timing-function( );
user-select @include user-select( none );

Tab Trigger Property
compact compact( $name-1, $name-2, $name-3, $name-4, $name-5, $name-6, $name-7, $name-8, $name-9, $name-10} );
fg-column $fg-column: 60px;
fg-gutter $fg-gutter: 25px;
fg-max-columns $fg-max-columns: 12;
flexgrid flex-grid(2,4);
flex-gutter flex-gutter(4);
golden-ratio golden-ratio( 14px, 1 );
gw-column $gw-column: 100px;
gw-gutter $gw-gutter: 40px;
grid-width grid-width( 4 );
linear-gradient @include background-image(linear-gradient(white 0, yellow 50%, transparent 50%));
modular-scale modular-scale( 14px, 1, 1.618 );
modular-scale-floor floor( modular-scale( 14px, 1, 1.618 ) );
modular-scale-ceil ceil( modular-scale( 14px, 1, 1.618 ) );
modular-scale-abs abs( modular-scale( 14px, 1, 1.618 ) );
radial-gradient @include background-image( radial-gradient( #1e5799, #3dc3d1 ) );
tint tint( red, 40% );
shade shade( blue, 60% );

Tab Trigger Property
button @include button( simple | shiny | pill, #ff0000 );
clearfix @include clearfix;
helvetica font-family: $helvetica;
georgia font-family: $georgia;
lucida-grande font-family: $lucida-grande;
monospace font-family: $monospace;
verdana font-family: $verdana;
hide-text @include hide-text;
all-text-inputs #{$all-text-inputs} { border: 1px solid green; }
all-text-inputs-hover #{$all-text-inputs-hover} { background: yellow; }
all-text-inputs-focus #{$all-text-inputs-focus} { background: white; }
inline-block @include inline-block;
position @include position( relative, 0px 0 0 100px );
retina @include retina-image( home-icon, 32px 20px );
size @include size( 30px 70px );
triangle @include triangle( 12px, gray, down );
prefix-for-webkit $prefix-for-webkit: true;
prefix-for-mozilla $prefix-for-mozilla: true;
prefix-for-microsoft $prefix-for-microsoft: true;
prefix-for-opera $prefix-for-opera: true;
prefix-for-spec $prefix-for-spec: true;
prefixer @include prefixer( box-sizing, $box, webkit moz spec );

Tab Trigger Property
outer-container @include outer-container;
span-columns @include span-columns( 6 of 8, inline-block );
row @include row( block | table );
shift @include shift( 2 );
pad @include pad( 30px default );
omega @include omega( 4n table );
remove-gutter @include omega( 4n table );
fill-parent @include fill-parent;
media-query @include media( min-width 320px max-width 480px 4 );
breakpoint new-breakpoint( min-width 320px max-width 480px 4 );

Streamline learning by having documentation at your fingertips, in your editor.

Derby's documentation section is composed of snippets that are meant to serve as a reference and a teaching aid. These docs can be called on at any time by typing docs and then the reference you are looking for like docsAnimation or docsBoxSizing.

This documentation is just a direct port over from the Bourbon site with some added adjustments like arguments some of these mixins can accept. For instance, when using docsAnimation you will notice an // args... section that will clue you in on how to best use the mixin.

Extending our example here is docsAnimation when output into your code for quick reference. Upon output all of the comments are highlighted immediately so you can delete them quickly once calling the argument

 * Animations
 * The animation mixins support comma separated lists of values, which allows different transitions 
 * for individual properties to be described in a single style rule. Each value in the list corresponds 
 * to the value at that same position in the other properties.
 * Source
 * https://github.com/thoughtbot/bourbon/blob/master/app/assets/stylesheets/css3/_animation.scss

box:hover {
  @include animation-name(scale, slide);
  @include animation-duration(2s);
  // args : ease | linear | ease-in | ease-out | ease-in-out
  @include animation-timing-function(ease);
  // args : infinite | 
  @include animation-iteration-count(infinite);

  // Animation shorthand works the same as the CSS3 animation shorthand
  @include animation(scale 1.0s ease-in, slide 2.0s ease);

Extending our example here is docsAnimation when output into your code for quick reference. Upon output all of the comments are highlighted immediately so you can delete them quickly once calling the argument

 * Modular Scale
 * Returns the modular scale of a given number. Must provide a number value for the first argument. 
 * The second argument is a required integer for an increment value: ...-3, -2, -1, 0, 1, 2, 3... 
 * The third value is the ratio number.
 * Note: The function can be wrapped in sass's abs(), floor(), or ceil() functions to get the 
 * absolute value, round down, or round up respectively.
 * Source
 * https://github.com/thoughtbot/bourbon/blob/master/app/assets/stylesheets/functions/_modular-scale.scss

div {
 // Increment Up GR with positive value
 font-size:        modular-scale(14px,   1, 1.618); // returns: 22.652px

 // Increment Down GR with negative value
 font-size:        modular-scale(14px,  -1, 1.618); // returns: 8.653px

 // Can be used with ceil(round up) or floor(round down)
 font-size: floor( modular-scale(14px, 1, 1.618) ); // returns: 22px
 font-size:  ceil( modular-scale(14px, 1, 1.618) ); // returns: 23px