Quickstart

Download the latest version of Kickstrap and move all the files to the location of your site. Bootstrap is already included. You shouldn't need anything else.

Note: By default, Kickstrap uses less.js client-side, requiring you to run Kickstrap from an actual server address, not "file://" or "C:/...".

The default index.html file is an example page with a similar, but shorter guide than this. To begin making your own site, I recommend using blank.html instead. This contains the Kickstrap HTML header and footer, with everything linked up.

Set your Root Directory

If you're running Kickstrap in a subdirectory (e.g. "http://domain.com/blog/"), be sure to set your @rootDir variable in kickstrap.less to that subdirectory beginning and ending with a slash (in this case, "/blog/").

Themes Change and customize your Kickstrap theme

Select a theme by opening your theme.less file. This should be at the same level as your Kickstrap folder.

      // BEGIN THEME
      // -----------

      @import "Kickstrap/themes/spacelab/variables.less";		
      @import "Kickstrap/themes/spacelab/bootswatch.less"; 

Now just make sure the @import lines are pointing to your theme. In the above example, you could change both instances of "spacelab" to "amelia" to use the included amelia theme instead.

      // BEGIN THEME
      // -----------

      @import "Kickstrap/themes/amelia/variables.less";		
      @import "Kickstrap/themes/amelia/bootswatch.less"; 

If you wish to expand on this theme, simply start writing CSS or LESS below those @imports. If you want to skip the theme, using Bootstrap's default instead, just get rid of the @import lines.

Apps Organize runtime extensions via simple keywords

Kickstrap comes with a few pre-bundled apps. You can find this in the Kickstrap/apps directory.

Apps, as well as many other settings, are set in kickstrap.less at the same level as your Kickstrap folder.

Adding and removing apps is as simple as adding or removing them from the comma-separated list.

   // APPS
   // -------

      @apps: "pinesnotify, bootstrap/tooltip, prettify, //knockout, //updater"; 
      // Name should match the app's folder name in Kickstrap/apps/.

However, you can also disable apps by typing two backslashes (//) in front of it. This is useful when you want to temporarily toggle off an app only to turn it back on later.

You may also notice single backslashes (/) can be used to refer to "subapps". For example, you can add the entire Bootstrap JS library with bootstrap or a single component of bootstrap such as bootstrap-tooltip with bootstrap/tooltip.

Troubleshooting

Learn to love your browser's console. Kickstrap uses this like a chat window to tell you what's going on.

To troubleshoot how your apps and other parts of your site are running, open your console using the shortcuts to your right.

If an app is not loading, you can troubleshoot its status via the arrays created there. Chrome, Safari, and Firefox with Firebug display these arrays best. For further troubleshooting, trying running the dependencies from the apps directly via good old html <script> and <link> tags.

For more information on troubleshooting, see debugging in the Extend section

How to open your browser's console

OS Browser Command
Mac Chrome Command + Opt + J
Firefox Command + Shift + L (Firebug)
Command + Opt + K (Default)
Safari Command + Opt + C
Windows Chrome Ctrl + Shift + J
Firefox Ctrl + Shift + L (Firebug)
Ctrl + Shift + K (Default)
Internet Explorer F12 then Ctrl + 3
Safari Ctrl + Opt + C

Page-Specific Apps

Due to limitations with LESS CSS, variables can only be set once. This means the @apps variable unfortunately cannot be appended with additional values, it is either used as-is page to page or not. Hopefully dynamic variables will be supported in the future.

By default, Kickstrap will load all the apps from settings.less on every page of your application. However, you may want to use different apps on different pages.

This requires removing @apps from settings.less and loading an individual apps.less file instead. Say you have an app you want to run only on your home page but you also have some apps you want across your application. Here is what your settings.less file looks like now:

settings.less

         // APPS
         // -------

         @apps: "qunit, bootstrap, homepage";
         ...
         

This will work fine, but it will load the "homepage" app on every single page. To correct this let's make a new apps.less file just for the homepage. We'll call it apps-home.less.

apps-home.less

         // APPS
         // -------

         @apps: "qunit, bootstrap, homepage";
         ...
         

For all other pages, we'll use apps.less with the homepage app removed.

apps.less

         // APPS
         // -------

         @apps: "qunit, bootstrap";
         ...
         

Settings Optimize your site's performance.

kickstrap.less is designed to be a customization hub for your Kickstrap site.

Here are some key parts of this file you may want to edit.

@apps
A comma-separated list of the apps to run. Single apps can be commented out using two backslashes (//).
@rootDir
The root of your site beginning and ending with a "/". This is automatically converted both as a global LESS and JavaScript variable to keep absolute paths consistent.
@universalResources
Set this to either "local" or "none". "local" means you'll be loading up universal dependencies (from the Kickstrap/apps/universal directory) from your local Kickstrap installation, "none" means you'll be skipping universal dependencies altogether. Universal dependencies are actually one big special app that loads strictly before any other apps. This is useful when you have more than one app that requires the same dependency, like jQuery UI. Running this in the universal app prevents each of those apps from loading it individually. We use the term "local" here as there may be support for running the universal app from a CDN in future Kickstrap releases
console.less
Kickstrap uses your browser's console like a chat window between itself and you. (Type "kickstrap.hello" in your console.) However, you may not want these diagnostics to show during production. Simply comment out this @import line to turn off Kickstrap console. Note, this only turns off console output from Kickstrap, and not the console itself.
caching.less
This @import is commented-out by default so you can see your LESS changes as they are made. When uncommented, client-side less.js will save your stylesheet output in the user's browser, making page load times very fast. Be advised, however, that it can be tricky to refresh the user's cache if needed. To refresh the cache manually, simply type clearCache() in your console.
Core Files
As the name implies, these are the core Kickstrap and Bootstrap files all atomically imported. As you build your site, consider commenting out the UI parts you don't use to improve page load performance.

Root Goodies Add a 404 page, .htaccess file, icons, and more.

Kickstrap tucks away some useful root files from the HTML5 Boilerplate project you may want to include in the root of your site. The reason why these are stashed this way is to maintain a clean file structure for new users and to remove the burden of deleting each and every one of these files if not needed.

To use the root goodies files, copy all contents from Kickstrap/extras/root goodies into your root.

These files include:

  • robots.txt
  • crossdomain.xml
  • 404.html
  • favicon.ico
  • Mobile device icons

Compiling LESS Generate good ol' CSS and speed up your site.

Using LESS.js client-side is great for rapidly building your site and seeing your changes. Unfortunately, however, it has a detrimental effect on page load time. Fortunately, there are some excellent free tools for compiling your LESS to css.

This very site has its LESS files compiled to a 67kb css file via LESS.app for Mac OS X

Follow these steps when compiling

  • Compile kickstrap.less. If using a gui, you should be able to just drag this file into the program.
  • Remove your link to kickstrap.less in your markup.
  • Remove the less.js script. Keeping this in your head will slow page load unnecessarily.

Important: Do not directly compile theme.less or any other .less file that is not kickstrap.less. Some compilers which "watch" for changes will try to compile theme.less as you edit and save it. This will cause it to lose the important variables and dependencies set in kickstrap.less.

Mac: I recommend LESS.app for Mac OS X. From the same developer is the paid and excellent CodeKit.

Windows: I recommend WinLess.

.

Not recommended: SimpLESS, Crunch have not worked well throughout the development of Kickstrap.

Keeping your page zippy

  • Comment out the parts you don't need from kickstrap.less.
  • Be sure less.js is removed from your head on all pages if you are comiling to css. You won't lose any Kickstrap functionality doing so.
  • Target IE browsers in your LESS/CSS with the html classes already in the included markup files (see the very top.) Simply make special IE rules children of .lt-ie8, etc.

LESS.js Errors

If you see that big red rectangle on your page instead of one of Bootswatch's wonderful themes, there are a few common reasons why this might happen:

  • You are trying to run your Kickstrap site in a browser with an address starting with anything other than "http://" or "https://" Less.js will automatically not run for security reasons.
  • There was a parsing error in your LESS. Check the console as there may be debugging information there (Client-side only.)
  • The less.js file cannot be found. Usually this is in Kickstrap/js/

Color Schemer Use Kickstrap's very own color scheming app.

To activate color schemer, already included in your Kickstrap/apps directory, just add it to the comma-separated @apps list.

API

The following commands should be run from the console while Color Schemer is open.

setColor('red')
Set the color to modify as red. In addition to plain-english words, you can also use hex values like "#e6e6e6", as well as hsv, hsl, and rgb. Use the same sytax as you would with CSS.
get(hex)
Get the currently set color as a hex value. Again, you can also use hsv, hsl, or rgb.
getTetrad([hex])
Generate a tetrad-based color scheme based on the currently set color. Optionally use a color code (hsl, hsv, rgb, or hex) as a parameter to have the values spit out in that code.
getTriad([hex])
Generate a triad-based color scheme.
getMono([hex])
Generate a monochromatic color scheme
getSplit([hex])
Generate a split-complement color scheme.
getAnalogous([hex])
Generate an analogous color scheme

You can also increase the saturation or luminosity of the selected color via the generated GUI on-screen. Just look for the four circles surrounding that color square.