Barebones

Head code

In order to serve your site responsively, and with good SEO practice, I recommend adding the following to your <head>

See this article for more information on building a responsive HTML meta tag.

<!DOCTYPE HTML>
<html>
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    ...

JS/CSS

Just use the CSS/JS file via a CDN.

Or download kickstart.css and kickstart.js and include in your html file.

kickstart.css  kickstart.js

  ...
    <link rel="stylesheet" href="//cdn.getkickstart.com/css/kickstart.min.css" />
  </head>
  <body>
    ...
    <script type="text/javascript" src="//cdn.getkickstart.com/js/kickstart.min.js"></script>
  </body>

Make sure any JavaScript code that uses k$ goes after the script tag inclusion of kickstart.js.

Notice that using this method will obviously not allow for using the semantic version of the docs.

<script type="text/javascript" src="//cdn.getkickstart.com/js/kickstart.min.js"></script>
<script>
  k$.tabs('.tabs');
</script>

Coffeescript/Sass

Using the source Sass and Coffeescript files in a project is easy. Simply clone the repo

$(~) git clone git@github.com:adamjgrant/kickstart.git --depth 1
# Omit the depth option if you intend to keep up to date with the
# Kickstart repo. Otherwise, this makes the cloning a lot faster.

In Kickstart, the main Sass file to compile is just the theme you are using. This can be found in lib-core/sass/themes

If you wish to use your own theme, you can place this wherever you like in your project. You'll just need to make sure your Sass loadPaths include the repo you just cloned. Otherwise, you'll get an error that some of the core libraries can't be found.

Rails

Install the Kickstart gem

Rails integration is Sass-only. This means you will need to use the mixins instead of things like .col-6.

Some of this is practical, some is philosophical, but if you really need the regular css despite the fact you're running a full sass-compilation environment, linking to kickstart.css directly is still an option.

You can either import kickstart into application.css or into individual files.

gem install "kickstart_rails"

Sample Gemfile

In your Gemfile, it's important to use Sass 3.4 or above. This means you should remove sass-rails as it uses an earlier version of Sass at the time of this writing.

# Do not use sass-rails
# gem 'sass-rails'

# Use Sass 3.4 and above.
gem 'sass', '~> 3.4'

# Add the kickstart_rails gem
gem 'kickstart_rails', '~> 3'

# Add autoprefixer
gem 'autoprefixer-rails'

Import in application.css

application.css must first be converted into .scss/.sass and not use any /* require statements. This is because sprockets does not see the sass variables. It will merely concatenate the compiled files together.

You can change this to use @import statements with an import to kickstart_rails at the top.

@import kickstart_rails;
@import mysassfile1.sass;
@import mysassfile2.sass;

JavaScript

Fortunately, adding the JavaScript is easier. Just add //= require kickstart_rails to the top of application.js

//= require kickstart_rails
//= require_tree .

Firing on ready

Some of your JavaScript will need to run once the DOM is ready. In Rails, this can be a little mysterious, especially when using jquery-ujs. Here's one way to ensure this code fires at the right time.

var ready = function() {
  // Your code
}
$(document).ready(ready);
$(document).on("page:load", ready);


function ready(fn) {
  if (document.readyState!='loading') {
    fn();
  }
  else {
    document.addEventListener('DOMContentLoaded', fn);
  }
}

ready(function() {
  // Your code
});

Autoprefixing

The gem uses autoprefixer to automatically prefix styles. If you want to specify your own autoprefixing rule, you'll just need to add a .yml file

See the instructions at the Autoprefixer docs

Gulp

My tool of choice for building all of Kickstart is gulp, plus a ton of extras. The easiest way to get started with a gulp implementation of kickstart is to simply clone the repo.

Setup instructions are in the README.md file at the repo.

Once you have your environment up and running, you should empty the jade folder and use kickstart-semantic.sass. This was designed specifically as an empty file with everything imported in.

Rename it to whatever you like and link to the resulting .css file in your html/jade

$(~) git clone git@github.com:adamjgrant/kickstart.git mywebsite --depth 1
# Omit the depth option if you intend to keep up to date with the
# Kickstart repo. Otherwise, this makes the cloning a lot faster.

# Install the dependencies
$(~) cd mywebsite
$(mywebsite) make setup

# If all goes well, this should launch your project.
$(mywebsite) gulp

Jekyll

Not yet compatible with GitHub Pages Unfortunately, GitHub runs Jekyll in safe mode which prevents it from loading the custom `load_paths` needed by Kickstart. Hopefully this will change soon.

Add Kickstart submodule

To add Kickstart to Jeykll 2, you'll of course need to start a new Jekyll project following the instructions on the Jekyll Docs

Afterwards, cd into the root of your Jekyll project and add Kickstart as a submodule.

$(myjekyllproject) git init # If you haven't already made your jekyll project a git repo

$(myjekyllproject) git submodule add https://github.com/adamjgrant/kickstart.git _kickstart

Edit load paths

You should now have a directory called _kickstart at the root of your project.

Now, open _config.yml and add the following to the bottom:

gems:
  - "autoprefixer-rails"
  - "jekyll-assets"

sass:
  load_paths:
    - "_sass"
    - "_kickstart"
    - "_kickstart/lib-core/sass"

assets:
  sources:
    - "_assets/javascripts"
    - "_assets/stylesheets"
    - "_sass"
    - "_kickstart"
    - "_kickstart/lib-core/sass"

Import Kickstart

Open css/main.scss and add this just below the @charset "utf-8"; line:

You can now add any Kickstart CSS you want to files imported from css/main.scss

If you're feeling daring, wipe out main.scss completely except for that @import line you added. You'll be running pure Kickstart, but will have to redesign your site a bit.

@import "lib/sass/themes/default/theme.sass";

Don't edit the submodule Any edits you make to the submodule, (i.e. the _kickstart directory you just created) can vanish without being retrievable in Git.

To avoid this, simply write your own CSS in the _sass directory. If you're editing a theme, you can simply copy the theme into _sass and import it from there. If you're creating a new theme, just copy the default theme from lib-core.

Add autoprefixer

You should also install autoprefixer so Kickstart works across modern browsers. To do this, simply add the following to your gemfile

source "http://rubygems.org"

gem "jekyll-assets"
gem "autoprefixer-rails"
gem "therubyracer", platforms: :ruby

Create an asset pipeline

To use Jekyll Assets, we'll need to edit the directory structure a bit. If you use Rails, this will be very familiar.

In the root of your Jekyll project, add an _assets directory with two children, stylesheets and javascripts.

_assets
  stylesheets
  javascripts
_includes
_layouts
_sass
...

In _assets/stylesheets, move in your main.scss file, renamed as main.css.scss

Also, remove any frontmatter (The ---s) from the file.

_assets
  stylesheets
  javascripts
_includes
_layouts
_sass
...

Reference your assets in the markup

Now we need to reference the post-processed CSS files that will be created. Open _includes/head.html and replace the link to main.css as follows.

<!-- Change this -->
<link rel="stylesheet" href="{{ "/css/main.css" | prepend: site.baseurl }}">

<!-- To this -->
{% stylesheet main.css %}

Node.js

Kickstart can easily be added as an npm package. This will download the entire repo to a node_modules folder.

npm install --save-dev kickstart-node

In your sass or scss file, import Kickstart via the theme you prefer:

Notice you may need a couple ../s before node_modules to point to the node_modules directory. This all depends on how you organized your project.

In the example, node_modules is at the same level as the scss/sass file.

@import node_modules/kickstart-node/lib/sass/themes/default/theme

Autoprefixer

The chances are very good that you'll need to include autoprefixer. This will add prefixes like -webkit- to bleeding edge css properties. Make sure this is included as part of your CSS compilation workflow.

Also available for Gulp