1# Bootstrap for Sass 2 3[![Build Status](https://secure.travis-ci.org/twbs/bootstrap-sass.png?branch=master)](http://travis-ci.org/twbs/bootstrap-sass) 4 5`bootstrap-sass` is a Sass-powered version of [Bootstrap](http://github.com/twbs/bootstrap), ready to drop right into your Sass powered applications. 6 7## Installation 8 9Please see the appropriate guide for your environment of choice: 10 11### a. Ruby on Rails 12 13`bootstrap-sass` is easy to drop into Rails with the asset pipeline. 14 15In your Gemfile you need to add the `bootstrap-sass` gem, and ensure that the `sass-rails` gem is present - it is added to new Rails applications by default. 16 17```ruby 18gem 'sass-rails', '>= 3.2' # sass-rails needs to be higher than 3.2 19gem 'bootstrap-sass', '~> 3.1.1' 20``` 21 22`bundle install` and restart your server to make the files available through the pipeline. 23 24 25#### Rails 3.2.x 26 27For Rails 3.2.x, make sure that all the gems are moved out of the `:assets` group, and `config.assets.initialize_on_precompile` is set to `true`. 28 29 30### b. Compass without Rails 31 32Install the gem 33```sh 34gem install bootstrap-sass 35``` 36 37If you have an existing Compass project: 38 39```ruby 40# config.rb: 41require 'bootstrap-sass' 42``` 43 44```console 45bundle exec compass install bootstrap 46``` 47 48If you are creating a new Compass project, you can generate it with bootstrap-sass support: 49 50```console 51bundle exec compass create my-new-project -r bootstrap-sass --using bootstrap 52``` 53 54This will create a new Compass project with the following files in it: 55 56* [_variables.scss](/templates/project/_variables.scss.erb) - all of bootstrap variables (override them here). 57* [styles.scss](/templates/project/styles.scss) - main project SCSS file, import `variables` and `bootstrap`. 58 59Some bootstrap-sass mixins may conflict with the Compass ones. 60If this happens, change the import order so that Compass mixins are loaded later. 61 62### c. Ruby without Compass / Rails 63 64Require the gem, and load paths and Sass helpers will be configured automatically: 65 66```ruby 67require 'bootstrap-sass' 68``` 69 70### d. Bower 71 72Using bootstrap-sass as a Bower package is still being tested and requires libsass master. You can install it with: 73 74```bash 75bower install git://github.com/twbs/bootstrap-sass.git 76``` 77 78`bootstrap-sass` is taken so make sure you use the Git URL above. 79 80Sass, JS, and all other assets are located at [vendor/assets](/vendor/assets). 81 82bootstrap-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][sass-precision] of 10 (default is 5). 83 84 85When using ruby Sass compiler with the bower version you can enforce the limit with: 86 87```ruby 88::Sass::Script::Number.precision = [10, ::Sass::Script::Number.precision].max 89``` 90 91#### JS and fonts 92 93Assets are discovered automatically on Rails, Sprockets, and Compass, using native asset path helpers. 94 95Otherwise the fonts are referenced as: 96 97```sass 98"#{$icon-font-path}/#{$icon-font-name}.eot" 99``` 100 101`$icon-font-path` defaults to `bootstrap/`. 102 103When not using an asset pipeline, you can copy fonts and JS from bootstrap-sass, they are located at [vendor/assets](/vendor/assets): 104 105```bash 106mkdir public/fonts 107cp -r $(bundle show bootstrap-sass)/vendor/assets/fonts/ public/fonts/ 108mkdir public/javascripts 109cp -r $(bundle show bootstrap-sass)/vendor/assets/javascripts/ public/javascripts/ 110``` 111 112## Usage 113 114### Sass 115 116Import Bootstrap into a Sass file (for example, `application.css.scss`) to get all of Bootstrap's styles, mixins and variables! 117We recommend against using `//= require` directives, since none of your other stylesheets will be [able to access][antirequire] the Bootstrap mixins or variables. 118 119```scss 120@import "bootstrap"; 121``` 122 123You can also include optional bootstrap theme: 124 125```scss 126@import "bootstrap/theme"; 127``` 128 129The full list of bootstrap variables can be found [here](http://getbootstrap.com/customize/#less-variables). You can override these by simply redefining the variable before the `@import` directive, e.g.: 130 131```scss 132$navbar-default-bg: #312312; 133$light-orange: #ff8c00; 134$navbar-default-color: $light-orange; 135 136@import "bootstrap"; 137``` 138 139You can also import components explicitly. To start with a full list of modules copy this file from the gem: 140 141```bash 142cp $(bundle show bootstrap-sass)/vendor/assets/stylesheets/bootstrap.scss \ 143 app/assets/stylesheets/bootstrap-custom.scss 144``` 145Comment out components you do not want from `bootstrap-custom`. 146 147In `application.sass`, replace `@import 'bootstrap'` with: 148 149```scss 150 @import 'bootstrap-custom'; 151``` 152 153### Javascript 154 155We have a helper that includes all Bootstrap javascripts. If you use Rails (or Sprockets separately), 156put this in your Javascript manifest (usually in `application.js`) to load the files in the [correct order](/vendor/assets/javascripts/bootstrap.js): 157 158```js 159// Loads all Bootstrap javascripts 160//= require bootstrap 161``` 162 163You can also load individual modules, provided you also require any dependencies. You can check dependencies in the [Bootstrap JS documentation][jsdocs]. 164 165```js 166//= require bootstrap/scrollspy 167//= require bootstrap/modal 168//= require bootstrap/dropdown 169``` 170 171--- 172 173## Development and Contributing 174 175If you'd like to help with the development of bootstrap-sass itself, read this section. 176 177### Upstream Converter 178 179Keeping bootstrap-sass in sync with upstream changes from Bootstrap used to be an error prone and time consuming manual process. With Bootstrap 3 we have introduced a converter that automates this. 180 181**Note: if you're just looking to *use* Bootstrap 3, see the [installation](#installation) section above.** 182 183Upstream changes to the Bootstrap project can now be pulled in using the `convert` rake task. 184 185Here's an example run that would pull down the master branch from the main [twbs/bootstrap](https://github.com/twbs/bootstrap) repo: 186 187 rake convert 188 189This will convert the latest LESS to SASS and update to the latest JS. 190To convert a specific branch or version, pass the branch name or the commit hash as the first task argument: 191 192 rake convert[e8a1df5f060bf7e6631554648e0abde150aedbe4] 193 194The latest converter script is located [here][converter] and does the following: 195 196* Converts upstream bootstrap LESS files to its matching SCSS file. 197* Copies all upstream JavaScript into `vendor/assets/javascripts/bootstrap` 198* Generates a javascript manifest at `vendor/assets/javascripts/bootstrap.js` 199* Copies all upstream font files into `vendor/assets/fonts/bootstrap` 200* Sets `Bootstrap::BOOTSTRAP_SHA` in [version.rb][version] to the branch sha. 201 202This converter fully converts original LESS to SCSS. Conversion is automatic but requires instructions for certain transformations (see converter output). 203Please submit GitHub issues tagged with `conversion`. 204 205## Credits 206 207bootstrap-sass has a number of major contributors: 208 209<!-- feel free to make these link wherever you wish --> 210* [Thomas McDonald](https://twitter.com/thomasmcdonald_) 211* [Tristan Harward](http://www.trisweb.com) 212* Peter Gumeson 213* [Gleb Mazovetskiy](https://github.com/glebm) 214 215and a [significant number of other contributors][contrib]. 216 217## You're in good company 218bootstrap-sass is used to build some awesome projects all over the web, including 219[Diaspora](http://diasporaproject.org/), [rails_admin](https://github.com/sferik/rails_admin), 220Michael Hartl's [Rails Tutorial](http://railstutorial.org/), [gitlabhq](http://gitlabhq.com/) and 221[kandan](http://kandanapp.com/). 222 223[converter]: https://github.com/twbs/bootstrap-sass/blob/master/tasks/converter/less_conversion.rb 224[version]: https://github.com/twbs/bootstrap-sass/blob/master/lib/bootstrap-sass/version.rb 225[contrib]: https://github.com/twbs/bootstrap-sass/graphs/contributors 226[antirequire]: https://github.com/twbs/bootstrap-sass/issues/79#issuecomment-4428595 227[jsdocs]: http://getbootstrap.com/javascript/#transitions 228[sass-precision]: http://sass-lang.com/documentation/Sass/Script/Number.html#precision-class_method 229