Submodules

Kickstart extensions are Git Submodules. Git Submodules are a neat way of including other git repositories in your own. You can keep them up-to-date with the main repo while not committing the entire contents of the repo with your project.

It's best to show how this works first, as there are some variations based on your environment and type of extension you'd like to install.

Rails users Using third-party components/themes is optional, but you'll need to do a few things first. See "Shimming rails" below before doing anything else.

Adding submodules

Each extension has a submodule creation command that should look something like the code you see here.

Running this in the terminal will create a folder (in this case "switch") and will download the contents of the repo much like git clone.

For components, you'll want to add submodules to your vendor directory. Themes should be added to the themes directory.

$ git submodule add git://github.com/adamjgrant/switch.git

If we cd into this folder, it acts just like a regular git repo. You can pull from the source and even push if you have permission.

All this directory changing and pulling can get hairy when using multiple submodules. Don't worry, there is a better way. Keep reading.

$(~) cd switch
$(switch) git status

On branch master
Your branch is up-to-date with 'origin/master'.

nothing to commit, working directory clean

Updating submodules

There are a few ways to update your submodules, depending on what you want to do. If you are cloning your project on another machine, you should refer to the documentation on cloning below.

To run a git pull for each submodule, you can use the foreach operator.

The second example achieves the same thing, but is wrapped up in your project's regular git pull.

The last command actually checks out the commits you just pulled down.

# Do one of these:
$(~) git submodule foreach git pull origin master
$(~) git pull origin master --recurse-submodules

Submodule path 'switch': checked out 'e9a72c2fddd41a0a4e25089790e3907582feb538'
Submodule path 'foo': checked out 'sd92j0vaskdjfjsdkfjna290304ud8sjf202ksdk'
Submodule path 'bar': checked out '293js0qjlkdsfj02jasdfkj20s9ij2ji2kjdlskj'
Submodule path 'toaster': checked out 'sdij29j20jdjfsldjkkkbbzxv982893jh034jjk'

# Then do this:
$(~) git submodule update --recursive

Cloning your project

When pulling down your project for the first time on a machine, the instructions for submodules are actually not the same as updating.

After cloning your project, you'll need to run the last command shown

Official documentation

$(~) git clone git@github.com:user/myrepo.git
...
$(~) cd myrepo
$(myrepo) git submodule update --recursive --init

Add a component

Use the right directory From here on, these directions will assume you are working at the directory where core or themes are located. In Node.js, this should be lib/sass/.

In Rails, this should be the parent directory of your Rails shim (see Shimming below.) Most likely, this is app/assets/stylesheets/

If you're using a clone of the repo, submodule the theme into vendor This will automatically create a folder with the name of the repository.

$(~) cd vendor

$(vendor) git submodule add git://github.com/adamjgrant/switch.git

Now let's add this to vendor/_index.sass so your theme automatically picks it up.

Notice here we have switch written twice (switch/switch) This is because we're importing the switch.sass file in the switch directory. The .sass on the last instance of switch can be omitted.

For the component you're using, pay close attention to the actual sass file you need to import.

@import switch/switch

At this point, you should have the component available, but we need to extend it in our theme.

Open your theme and add a mixin that extends the component. For switch, we would do this (see code)

We add the $color parameter only because that's one of the params in the actual mixin. If the author writes good documentation on their component, this information should be available on the component detail page. Otherwise, you may need to dig into the sass file itself to understand how to integrate it.

=switch($args...)
  +switch-default($args...)

We now have a fully-functioning mixin that we can even extend inside our theme file. However, it's not yet available to CSS. Let's @include it in a class.

.switch
  +switch

That should be all we need to make the CSS available for us from the component. Further documentation on markup needed and extras will depend on the component being used.

Add a theme

Submodule your theme (See "Adding a submodule at the top") into the themes directory.

$(themes) git submodule add git://github.com/adamjgrant/mynewtheme.git

Now you'll need to change the theme from _default to whatever theme you chose.

Depending on your implementation, you'll probably find this @import in your main sass file.

Here is an example from kickstart-semantic.sass

//  Kickstart Semantic
//  ==================
//  This is just a starter file for using Kickstart via Sass
//  Rename this file to something you like (e.g. style.sass) and import it by
//  the same .css name from your html/jade file.

// Choose your theme
@import themes/mynewtheme/_theme.sass

// Now write your own Sass

Don't edit 3rd party themes As git submodules, there is significant risk that changes to a third-party will be lost, both from your code and from your version control. It's much safer to override the CSS rules in a separate file in your version control that comes after the third-party theme in your import flow.

Shimming for rails

You may need to make a few adjustments in a Rails environment to get third-party extensions working.

Consider the fact that the @import paths in your theme are actually pointing to the kickstart_rails gem, installed deep in your filesystem.

Vendor library

By default, the vendor library points to vendor/_index.sass in the kickstart_rails gem. If you want to add components, you'll need to create the vendor directory in app/assets/stylesheets.

Now create _index.sass in vendor. The complete commands to do this are shown.

$(~) cd app/assets/stylesheets
$(stylesheets) mkdir vendor
$(stylesheets) touch vendor/_index.sass

Other directories

When installing themes, you should install them in a themes directory under app/assets/stylesheets.

$(stylesheets) mkdir themes