1 | # Bootstrap for Sass [![Gem Version](https://badge.fury.io/rb/bootstrap-sass.svg)](http://badge.fury.io/rb/bootstrap-sass) [![Bower Version](https://badge.fury.io/bo/bootstrap-sass-official.svg)](http://badge.fury.io/bo/bootstrap-sass-official) [![Build Status](http://img.shields.io/travis/twbs/bootstrap-sass.svg)](http://travis-ci.org/twbs/bootstrap-sass)
|
2 |
|
3 | `bootstrap-sass` is a Sass-powered version of [Bootstrap](http://github.com/twbs/bootstrap), ready to drop right into your Sass powered applications.
|
4 |
|
5 | ## Installation
|
6 |
|
7 | Please see the appropriate guide for your environment of choice:
|
8 |
|
9 | * [Ruby on Rails](#a-ruby-on-rails).
|
10 | * [Compass](#b-compass-without-rails) not on Rails.
|
11 | * [Bower](#c-bower).
|
12 |
|
13 | ### a. Ruby on Rails
|
14 |
|
15 | `bootstrap-sass` is easy to drop into Rails with the asset pipeline.
|
16 |
|
17 | In 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.
|
18 |
|
19 | ```ruby
|
20 | gem 'bootstrap-sass', '~> 3.3.1'
|
21 | gem 'sass-rails', '>= 3.2'
|
22 | ```
|
23 |
|
24 | It is also recommended to use [Autoprefixer](https://github.com/ai/autoprefixer-rails) with Bootstrap
|
25 | to add browser vendor prefixes automatically. Simply add the gem:
|
26 |
|
27 | ```ruby
|
28 | gem 'autoprefixer-rails'
|
29 | ```
|
30 |
|
31 | `bundle install` and restart your server to make the files available through the pipeline.
|
32 |
|
33 | Import Bootstrap styles in `app/assets/stylesheets/application.css.scss`:
|
34 |
|
35 | ```scss
|
36 | // "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
|
37 | @import "bootstrap-sprockets";
|
38 | @import "bootstrap";
|
39 | ```
|
40 |
|
41 | `bootstrap-sprockets` must be imported before `bootstrap` for the icon fonts to work.
|
42 |
|
43 | Make sure the file has `.css.scss` extension (or `.css.sass` for Sass syntax). If you have just generated a new Rails app,
|
44 | it may come with a `.css` file instead. If this file exists, it will be served instead of Sass, so remove it:
|
45 |
|
46 | ```console
|
47 | $ rm app/assets/stylesheets/application.css
|
48 | ```
|
49 |
|
50 | Do not use `//= require` in Sass or your other stylesheets will not be [able to access][antirequire] the Bootstrap mixins or variables.
|
51 |
|
52 | Require Bootstrap Javascripts in `app/assets/javascripts/application.js`:
|
53 |
|
54 | ```js
|
55 | //= require jquery
|
56 | //= require bootstrap-sprockets
|
57 | ```
|
58 |
|
59 | #### Bower with Rails
|
60 |
|
61 | When using [bootstrap-sass Bower package](#c-bower) instead of the gem in Rails, configure assets in `config/application.rb`:
|
62 |
|
63 | ```ruby
|
64 | # Bower asset paths
|
65 | root.join('vendor', 'assets', 'bower_components').to_s.tap do |bower_path|
|
66 | config.sass.load_paths << bower_path
|
67 | config.assets.paths << bower_path
|
68 | end
|
69 | # Precompile Bootstrap fonts
|
70 | config.assets.precompile << %r(bootstrap-sass/assets/fonts/bootstrap/[\w-]+\.(?:eot|svg|ttf|woff)$)
|
71 | # Minimum Sass number precision required by bootstrap-sass
|
72 | ::Sass::Script::Number.precision = [10, ::Sass::Script::Number.precision].max
|
73 | ```
|
74 |
|
75 | Replace Bootstrap `@import` statements in `application.css.scss` with:
|
76 |
|
77 | ```scss
|
78 | $icon-font-path: "bootstrap-sass/assets/fonts/bootstrap/";
|
79 | @import "bootstrap-sass/assets/stylesheets/bootstrap-sprockets";
|
80 | @import "bootstrap-sass/assets/stylesheets/bootstrap";
|
81 | ```
|
82 |
|
83 | Replace Bootstrap `require` directive in `application.js` with:
|
84 |
|
85 | ```js
|
86 | //= require bootstrap-sass/assets/javascripts/bootstrap-sprockets
|
87 | ```
|
88 |
|
89 | #### Rails 4.x
|
90 |
|
91 | Please make sure `sprockets-rails` is at least v2.1.4.
|
92 |
|
93 | #### Rails 3.2.x
|
94 |
|
95 | bootstrap-sass is no longer compatible with Rails 3. The latest version of bootstrap-sass compatible with Rails 3.2 is v3.1.1.0.
|
96 |
|
97 | ### b. Compass without Rails
|
98 |
|
99 | Install the gem
|
100 | ```sh
|
101 | gem install bootstrap-sass
|
102 | ```
|
103 |
|
104 | If you have an existing Compass project:
|
105 |
|
106 | ```ruby
|
107 | # config.rb:
|
108 | require 'bootstrap-sass'
|
109 | ```
|
110 |
|
111 | ```console
|
112 | $ bundle exec compass install bootstrap
|
113 | ```
|
114 |
|
115 | If you are creating a new Compass project, you can generate it with bootstrap-sass support:
|
116 |
|
117 | ```console
|
118 | $ bundle exec compass create my-new-project -r bootstrap-sass --using bootstrap
|
119 | ```
|
120 |
|
121 | or, alternatively, if you're not using a Gemfile for your dependencies:
|
122 |
|
123 | ```console
|
124 | $ compass create my-new-project -r bootstrap-sass --using bootstrap
|
125 | ```
|
126 |
|
127 | This will create a new Compass project with the following files in it:
|
128 |
|
129 | * [styles.sass](/templates/project/styles.sass) - main project Sass file, imports Bootstrap and variables.
|
130 | * [_bootstrap-variables.sass](/templates/project/_bootstrap-variables.sass) - all of Bootstrap variables, override them here.
|
131 |
|
132 | Some bootstrap-sass mixins may conflict with the Compass ones.
|
133 | If this happens, change the import order so that Compass mixins are loaded later.
|
134 |
|
135 | ### c. Bower
|
136 |
|
137 | Using bootstrap-sass as a Bower package is still being tested. It is compatible with node-sass 0.8.3+. You can install it with:
|
138 |
|
139 | ```console
|
140 | $ bower install bootstrap-sass-official
|
141 | ```
|
142 |
|
143 | `bootstrap-sass` is taken so make sure you use the command above.
|
144 |
|
145 | Sass, JS, and all other assets are located at [assets](/assets).
|
146 |
|
147 | By default, `bower.json` main field list only the main `bootstrap.scss` and all the static assets (fonts and JS).
|
148 | This is compatible by default with asset managers such as [wiredep](https://github.com/taptapship/wiredep).
|
149 |
|
150 | #### Node.js Mincer
|
151 |
|
152 | If you use [mincer][mincer] with node-sass, import bootstrap into like so:
|
153 |
|
154 | In `application.css.ejs.scss` (NB **.css.ejs.css**):
|
155 |
|
156 | ```scss
|
157 | // Import mincer asset paths helper integration
|
158 | @import "bootstrap-mincer";
|
159 | @import "bootstrap";
|
160 | ```
|
161 |
|
162 | In `application.js`:
|
163 |
|
164 | ```js
|
165 | //= require bootstrap-sprockets
|
166 | ```
|
167 |
|
168 | See also this [example manifest.js](/test/dummy_node_mincer/manifest.js) for mincer.
|
169 |
|
170 |
|
171 | ### Configuration
|
172 |
|
173 | #### Sass
|
174 |
|
175 | By default all of Bootstrap is imported.
|
176 |
|
177 | You can also import components explicitly. To start with a full list of modules copy
|
178 | [`_bootstrap.scss`](assets/stylesheets/_bootstrap.scss) file into your assets as `_bootstrap-custom.scss`.
|
179 | Then comment out components you do not want from `_bootstrap-custom`.
|
180 | In the application Sass file, replace `@import 'bootstrap'` with:
|
181 |
|
182 | ```scss
|
183 | @import 'bootstrap-custom';
|
184 | ```
|
185 |
|
186 | #### Sass: Number Precision
|
187 |
|
188 | bootstrap-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][sass-precision] of 10 (default is 5).
|
189 |
|
190 | Precision is set for Rails and Compass automatically.
|
191 | When using ruby Sass compiler standalone or with the Bower version you can set it with:
|
192 |
|
193 | ```ruby
|
194 | ::Sass::Script::Number.precision = [10, ::Sass::Script::Number.precision].max
|
195 | ```
|
196 |
|
197 | Note that libsass and node-sass do not currently support the precision option, due to an open bug ([bug #364](https://github.com/sass/libsass/issues/364)) in libsass.
|
198 |
|
199 |
|
200 | #### Sass: Autoprefixer
|
201 |
|
202 | Using [Autoprefixer][autoprefixer] with Bootstrap is recommended.
|
203 | [Autoprefixer][autoprefixer] adds vendor prefixes to CSS rules using values from [Can I Use](http://caniuse.com/).
|
204 |
|
205 | #### JavaScript
|
206 |
|
207 | [`assets/javascripts/bootstrap.js`](/assets/javascripts/bootstrap.js) contains all of Bootstrap JavaScript,
|
208 | concatenated in the [correct order](/assets/javascripts/bootstrap-sprockets.js).
|
209 |
|
210 |
|
211 | #### JavaScript with Sprockets or Mincer
|
212 |
|
213 | If you use Sprockets or Mincer, you can require `bootstrap-sprockets` instead to load the individual modules:
|
214 |
|
215 | ```js
|
216 | // Load all Bootstrap JavaScript
|
217 | //= require bootstrap-sprockets
|
218 | ```
|
219 |
|
220 | You can also load individual modules, provided you also require any dependencies.
|
221 | You can check dependencies in the [Bootstrap JS documentation][jsdocs].
|
222 |
|
223 | ```js
|
224 | //= require bootstrap/scrollspy
|
225 | //= require bootstrap/modal
|
226 | //= require bootstrap/dropdown
|
227 | ```
|
228 |
|
229 | #### Fonts
|
230 |
|
231 | The fonts are referenced as:
|
232 |
|
233 | ```scss
|
234 | "#{$icon-font-path}#{$icon-font-name}.eot"
|
235 | ```
|
236 |
|
237 | `$icon-font-path` defaults to `bootstrap/` if asset path helpers are used, and `../fonts/bootstrap/` otherwise.
|
238 |
|
239 | When using bootstrap-sass with Compass, Sprockets, or Mincer, you **must** import the relevant path helpers before Bootstrap itself, for example:
|
240 |
|
241 | ```scss
|
242 | @import "bootstrap-compass";
|
243 | @import "bootstrap";
|
244 | ```
|
245 |
|
246 | ## Usage
|
247 |
|
248 | ### Sass
|
249 |
|
250 | Import Bootstrap into a Sass file (for example, application.css.scss) to get all of Bootstrap's styles, mixins and variables!
|
251 |
|
252 | ```scss
|
253 | @import "bootstrap";
|
254 | ```
|
255 |
|
256 | You can also include optional bootstrap theme:
|
257 |
|
258 | ```scss
|
259 | @import "bootstrap/theme";
|
260 | ```
|
261 |
|
262 | The 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.:
|
263 |
|
264 | ```scss
|
265 | $navbar-default-bg: #312312;
|
266 | $light-orange: #ff8c00;
|
267 | $navbar-default-color: $light-orange;
|
268 |
|
269 | @import "bootstrap";
|
270 | ```
|
271 |
|
272 | ## Version
|
273 |
|
274 | `bootstrap-sass` version reflects the upstream version, with an additional number for Sass-specific changes.
|
275 |
|
276 | Always refer to [CHANGELOG.md](/CHANGELOG.md) when upgrading.
|
277 |
|
278 | ---
|
279 |
|
280 | ## Development and Contributing
|
281 |
|
282 | If you'd like to help with the development of bootstrap-sass itself, read this section.
|
283 |
|
284 | ### Upstream Converter
|
285 |
|
286 | Keeping 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.
|
287 |
|
288 | **Note: if you're just looking to *use* Bootstrap 3, see the [installation](#installation) section above.**
|
289 |
|
290 | Upstream changes to the Bootstrap project can now be pulled in using the `convert` rake task.
|
291 |
|
292 | Here's an example run that would pull down the master branch from the main [twbs/bootstrap](https://github.com/twbs/bootstrap) repo:
|
293 |
|
294 | rake convert
|
295 |
|
296 | This will convert the latest LESS to Sass and update to the latest JS.
|
297 | To convert a specific branch or version, pass the branch name or the commit hash as the first task argument:
|
298 |
|
299 | rake convert[e8a1df5f060bf7e6631554648e0abde150aedbe4]
|
300 |
|
301 | The latest converter script is located [here][converter] and does the following:
|
302 |
|
303 | * Converts upstream bootstrap LESS files to its matching SCSS file.
|
304 | * Copies all upstream JavaScript into `assets/javascripts/bootstrap`, an Sprockets manifest at `assets/javascripts/bootstrap-sprockets.js`, and a concatenation at `assets/javascripts/bootstrap.js`.
|
305 | * Copies all upstream font files into `assets/fonts/bootstrap`.
|
306 | * Sets `Bootstrap::BOOTSTRAP_SHA` in [version.rb][version] to the branch sha.
|
307 |
|
308 | This converter fully converts original LESS to SCSS. Conversion is automatic but requires instructions for certain transformations (see converter output).
|
309 | Please submit GitHub issues tagged with `conversion`.
|
310 |
|
311 | ## Credits
|
312 |
|
313 | bootstrap-sass has a number of major contributors:
|
314 |
|
315 |
|
316 | * [Thomas McDonald](https://twitter.com/thomasmcdonald_)
|
317 | * [Tristan Harward](http://www.trisweb.com)
|
318 | * Peter Gumeson
|
319 | * [Gleb Mazovetskiy](https://github.com/glebm)
|
320 |
|
321 | and a [significant number of other contributors][contrib].
|
322 |
|
323 | ## You're in good company
|
324 | bootstrap-sass is used to build some awesome projects all over the web, including
|
325 | [Diaspora](http://diasporaproject.org/), [rails_admin](https://github.com/sferik/rails_admin),
|
326 | Michael Hartl's [Rails Tutorial](http://railstutorial.org/), [gitlabhq](http://gitlabhq.com/) and
|
327 | [kandan](http://kandanapp.com/).
|
328 |
|
329 | [converter]: https://github.com/twbs/bootstrap-sass/blob/master/tasks/converter/less_conversion.rb
|
330 | [version]: https://github.com/twbs/bootstrap-sass/blob/master/lib/bootstrap-sass/version.rb
|
331 | [contrib]: https://github.com/twbs/bootstrap-sass/graphs/contributors
|
332 | [antirequire]: https://github.com/twbs/bootstrap-sass/issues/79#issuecomment-4428595
|
333 | [jsdocs]: http://getbootstrap.com/javascript/#transitions
|
334 | [sass-precision]: http://sass-lang.com/documentation/Sass/Script/Number.html#precision-class_method
|
335 | [mincer]: https://github.com/nodeca/mincer
|
336 | [autoprefixer]: https://github.com/ai/autoprefixer
|