README.md 12 KB
Newer Older
Thomas Park's avatar
Thomas Park committed
1
2
3
4
5
# Bootstrap for Sass
[![Gem Version](https://badge.fury.io/rb/bootstrap-sass.svg)](http://badge.fury.io/rb/bootstrap-sass)
[![npm version](https://img.shields.io/npm/v/bootstrap-sass.svg?style=flat)](https://www.npmjs.com/package/bootstrap-sass)
[![Bower Version](https://badge.fury.io/bo/bootstrap-sass.svg)](http://badge.fury.io/bo/bootstrap-sass)
[![Build Status](http://img.shields.io/travis/twbs/bootstrap-sass.svg)](http://travis-ci.org/twbs/bootstrap-sass)
Corey Sewell's avatar
Corey Sewell committed
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

`bootstrap-sass` is a Sass-powered version of [Bootstrap](http://github.com/twbs/bootstrap), ready to drop right into your Sass powered applications.

## Installation

Please see the appropriate guide for your environment of choice:

* [Ruby on Rails](#a-ruby-on-rails).
* [Compass](#b-compass-without-rails) not on Rails.
* [Bower](#c-bower).

### a. Ruby on Rails

`bootstrap-sass` is easy to drop into Rails with the asset pipeline.

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.

```ruby
Thomas Park's avatar
Thomas Park committed
24
gem 'bootstrap-sass', '~> 3.3.4'
Corey Sewell's avatar
Corey Sewell committed
25
26
27
28
29
gem 'sass-rails', '>= 3.2'
```

`bundle install` and restart your server to make the files available through the pipeline.

Thomas Park's avatar
Thomas Park committed
30
Import Bootstrap styles in `app/assets/stylesheets/application.scss`:
Corey Sewell's avatar
Corey Sewell committed
31
32
33
34
35
36
37
38
39

```scss
// "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
@import "bootstrap-sprockets";
@import "bootstrap";
```

`bootstrap-sprockets` must be imported before `bootstrap` for the icon fonts to work.

Thomas Park's avatar
Thomas Park committed
40
Make sure the file has `.scss` extension (or `.sass` for Sass syntax). If you have just generated a new Rails app,
Thomas Park's avatar
Thomas Park committed
41
it may come with a `.css` file instead. If this file exists, it will be served instead of Sass, so rename it:
Corey Sewell's avatar
Corey Sewell committed
42
43

```console
Thomas Park's avatar
Thomas Park committed
44
$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
Corey Sewell's avatar
Corey Sewell committed
45
46
```

Thomas Park's avatar
Thomas Park committed
47
48
Then, remove all the `//= require` and `//= require_tree` statements from the file. Instead, use `@import` to import Sass files.

Corey Sewell's avatar
Corey Sewell committed
49
50
51
52
53
54
55
56
57
Do not use `//= require` in Sass or your other stylesheets will not be [able to access][antirequire] the Bootstrap mixins or variables.

Require Bootstrap Javascripts in `app/assets/javascripts/application.js`:

```js
//= require jquery
//= require bootstrap-sprockets
```

Thomas Park's avatar
Thomas Park committed
58
59
60
61
62
`bootstrap-sprockets` and `bootstrap` [should not both be included](https://github.com/twbs/bootstrap-sass/issues/829#issuecomment-75153827) in `application.js`.

`bootstrap-sprockets` provides individual Bootstrap Javascript files (`alert.js` or `dropdown.js`, for example), while
`bootstrap` provides a concatenated file containing all Bootstrap Javascripts.

Corey Sewell's avatar
Corey Sewell committed
63
64
65
66
67
68
69
70
71
72
73
#### Bower with Rails

When using [bootstrap-sass Bower package](#c-bower) instead of the gem in Rails, configure assets in `config/application.rb`:

```ruby
# Bower asset paths
root.join('vendor', 'assets', 'bower_components').to_s.tap do |bower_path|
  config.sass.load_paths << bower_path
  config.assets.paths << bower_path
end
# Precompile Bootstrap fonts
Thomas Park's avatar
Thomas Park committed
74
config.assets.precompile << %r(bootstrap-sass/assets/fonts/bootstrap/[\w-]+\.(?:eot|svg|ttf|woff2?)$)
Corey Sewell's avatar
Corey Sewell committed
75
# Minimum Sass number precision required by bootstrap-sass
Thomas Park's avatar
Thomas Park committed
76
::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
Corey Sewell's avatar
Corey Sewell committed
77
78
```

Thomas Park's avatar
Thomas Park committed
79
Replace Bootstrap `@import` statements in `application.scss` with:
Corey Sewell's avatar
Corey Sewell committed
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

```scss
$icon-font-path: "bootstrap-sass/assets/fonts/bootstrap/";
@import "bootstrap-sass/assets/stylesheets/bootstrap-sprockets";
@import "bootstrap-sass/assets/stylesheets/bootstrap";
```

Replace Bootstrap `require` directive in `application.js` with:

```js
//= require bootstrap-sass/assets/javascripts/bootstrap-sprockets
```

#### Rails 4.x

Please make sure `sprockets-rails` is at least v2.1.4.

#### Rails 3.2.x

Thomas Park's avatar
Thomas Park committed
99
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.
Corey Sewell's avatar
Corey Sewell committed
100
101
102

### b. Compass without Rails

Thomas Park's avatar
Thomas Park committed
103
104
105
106
Install the gem:

```console
$ gem install bootstrap-sass
Corey Sewell's avatar
Corey Sewell committed
107
108
109
110
```

If you have an existing Compass project:

Thomas Park's avatar
Thomas Park committed
111
1. Require `bootstrap-sass` in `config.rb`:
Corey Sewell's avatar
Corey Sewell committed
112

Thomas Park's avatar
Thomas Park committed
113
114
115
116
117
118
119
120
121
    ```ruby
    require 'bootstrap-sass'
    ```

2. Install Bootstrap with:

    ```console
    $ bundle exec compass install bootstrap -r bootstrap-sass
    ```
Corey Sewell's avatar
Corey Sewell committed
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

If you are creating a new Compass project, you can generate it with bootstrap-sass support:

```console
$ bundle exec compass create my-new-project -r bootstrap-sass --using bootstrap
```

or, alternatively, if you're not using a Gemfile for your dependencies:

```console
$ compass create my-new-project -r bootstrap-sass --using bootstrap
```

This will create a new Compass project with the following files in it:

* [styles.sass](/templates/project/styles.sass) - main project Sass file, imports Bootstrap and variables.
* [_bootstrap-variables.sass](/templates/project/_bootstrap-variables.sass) - all of Bootstrap variables, override them here.

Some bootstrap-sass mixins may conflict with the Compass ones.
If this happens, change the import order so that Compass mixins are loaded later.

### c. Bower

Thomas Park's avatar
Thomas Park committed
145
bootstrap-sass Bower package is compatible with node-sass 1.2.3+. You can install it with:
Corey Sewell's avatar
Corey Sewell committed
146
147

```console
Thomas Park's avatar
Thomas Park committed
148
$ bower install bootstrap-sass
Corey Sewell's avatar
Corey Sewell committed
149
150
151
152
```

Sass, JS, and all other assets are located at [assets](/assets).

Thomas Park's avatar
Thomas Park committed
153
By default, `bower.json` main field list only the main `_bootstrap.scss` and all the static assets (fonts and JS).
Corey Sewell's avatar
Corey Sewell committed
154
155
156
157
This is compatible by default with asset managers such as [wiredep](https://github.com/taptapship/wiredep).

#### Node.js Mincer

Thomas Park's avatar
Thomas Park committed
158
If you use [mincer][mincer] with node-sass, import bootstrap like so:
Corey Sewell's avatar
Corey Sewell committed
159

Thomas Park's avatar
Thomas Park committed
160
In `application.css.ejs.scss` (NB **.css.ejs.scss**):
Corey Sewell's avatar
Corey Sewell committed
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193

```scss
// Import mincer asset paths helper integration
@import "bootstrap-mincer";
@import "bootstrap";
```

In `application.js`:

```js
//= require bootstrap-sprockets
```

See also this [example manifest.js](/test/dummy_node_mincer/manifest.js) for mincer.


### Configuration

#### Sass

By default all of Bootstrap is imported.

You can also import components explicitly. To start with a full list of modules copy
[`_bootstrap.scss`](assets/stylesheets/_bootstrap.scss) file into your assets as `_bootstrap-custom.scss`.
Then comment out components you do not want from `_bootstrap-custom`.
In the application Sass file, replace `@import 'bootstrap'` with:

```scss
@import 'bootstrap-custom';
```

#### Sass: Number Precision

Thomas Park's avatar
Thomas Park committed
194
bootstrap-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][sass-precision] of 8 (default is 5).
Corey Sewell's avatar
Corey Sewell committed
195
196
197
198
199

Precision is set for Rails and Compass automatically.
When using ruby Sass compiler standalone or with the Bower version you can set it with:

```ruby
Thomas Park's avatar
Thomas Park committed
200
::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
Corey Sewell's avatar
Corey Sewell committed
201
202
203
204
```

#### Sass: Autoprefixer

Thomas Park's avatar
Thomas Park committed
205
Bootstrap requires the use of [Autoprefixer][autoprefixer].
Corey Sewell's avatar
Corey Sewell committed
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
[Autoprefixer][autoprefixer] adds vendor prefixes to CSS rules using values from [Can I Use](http://caniuse.com/).

#### JavaScript

[`assets/javascripts/bootstrap.js`](/assets/javascripts/bootstrap.js) contains all of Bootstrap JavaScript,
concatenated in the [correct order](/assets/javascripts/bootstrap-sprockets.js).


#### JavaScript with Sprockets or Mincer

If you use Sprockets or Mincer, you can require `bootstrap-sprockets` instead to load the individual modules:

```js
// Load all Bootstrap JavaScript
//= require bootstrap-sprockets
```

You can also load individual modules, provided you also require any dependencies.
You can check dependencies in the [Bootstrap JS documentation][jsdocs].

```js
//= require bootstrap/scrollspy
//= require bootstrap/modal
//= require bootstrap/dropdown
```

#### Fonts

The fonts are referenced as:

```scss
"#{$icon-font-path}#{$icon-font-name}.eot"
```

`$icon-font-path` defaults to `bootstrap/` if asset path helpers are used, and `../fonts/bootstrap/` otherwise.

When using bootstrap-sass with Compass, Sprockets, or Mincer, you **must** import the relevant path helpers before Bootstrap itself, for example:

```scss
@import "bootstrap-compass";
@import "bootstrap";
```

## Usage

### Sass

Thomas Park's avatar
Thomas Park committed
253
Import Bootstrap into a Sass file (for example, application.scss) to get all of Bootstrap's styles, mixins and variables!
Corey Sewell's avatar
Corey Sewell committed
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276

```scss
@import "bootstrap";
```

You can also include optional bootstrap theme:

```scss
@import "bootstrap/theme";
```

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.:

```scss
$navbar-default-bg: #312312;
$light-orange: #ff8c00;
$navbar-default-color: $light-orange;

@import "bootstrap";
```

## Version

Thomas Park's avatar
Thomas Park committed
277
278
279
280
281
282
283
284
285
286
287
288
289
290
Bootstrap for Sass version may differ from the upstream version in the last number, known as
[MINOR](http://semver.org/spec/v2.0.0.html). The minor version may be ahead of the corresponding upstream minor.
This happens when we need to release Sass-specific changes.

Before v3.3.2, Bootstrap for Sass version used to reflect the upstream version, with an additional number for
Sass-specific changes. This was changed due to Bower and npm compatibility issues.

The upstream versions vs the Bootstrap for Sass versions are:

| Upstream |    Sass |
|---------:|--------:|
|    3.3.4 |   3.3.4 |
|    3.3.2 |   3.3.3 |
| <= 3.3.1 | 3.3.1.x |
Corey Sewell's avatar
Corey Sewell committed
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319

Always refer to [CHANGELOG.md](/CHANGELOG.md) when upgrading.

---

## Development and Contributing

If you'd like to help with the development of bootstrap-sass itself, read this section.

### Upstream Converter

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.

**Note: if you're just looking to *use* Bootstrap 3, see the [installation](#installation) section above.**

Upstream changes to the Bootstrap project can now be pulled in using the `convert` rake task.

Here's an example run that would pull down the master branch from the main [twbs/bootstrap](https://github.com/twbs/bootstrap) repo:

    rake convert

This will convert the latest LESS to Sass and update to the latest JS.
To convert a specific branch or version, pass the branch name or the commit hash as the first task argument:

    rake convert[e8a1df5f060bf7e6631554648e0abde150aedbe4]

The latest converter script is located [here][converter] and does the following:

* Converts upstream bootstrap LESS files to its matching SCSS file.
Thomas Park's avatar
Thomas Park committed
320
* Copies all upstream JavaScript into `assets/javascripts/bootstrap`, a Sprockets manifest at `assets/javascripts/bootstrap-sprockets.js`, and a concatenation at `assets/javascripts/bootstrap.js`.
Corey Sewell's avatar
Corey Sewell committed
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
* Copies all upstream font files into `assets/fonts/bootstrap`.
* Sets `Bootstrap::BOOTSTRAP_SHA` in [version.rb][version] to the branch sha.

This converter fully converts original LESS to SCSS. Conversion is automatic but requires instructions for certain transformations (see converter output).
Please submit GitHub issues tagged with `conversion`.

## Credits

bootstrap-sass has a number of major contributors:

<!-- feel free to make these link wherever you wish -->
* [Thomas McDonald](https://twitter.com/thomasmcdonald_)
* [Tristan Harward](http://www.trisweb.com)
* Peter Gumeson
* [Gleb Mazovetskiy](https://github.com/glebm)

and a [significant number of other contributors][contrib].

## You're in good company
bootstrap-sass is used to build some awesome projects all over the web, including
Thomas Park's avatar
Thomas Park committed
341
[Diaspora](https://diasporafoundation.org/), [rails_admin](https://github.com/sferik/rails_admin),
Corey Sewell's avatar
Corey Sewell committed
342
Michael Hartl's [Rails Tutorial](http://railstutorial.org/), [gitlabhq](http://gitlabhq.com/) and
Thomas Park's avatar
Thomas Park committed
343
[kandan](http://kandan.io/).
Corey Sewell's avatar
Corey Sewell committed
344
345
346
347
348
349

[converter]: https://github.com/twbs/bootstrap-sass/blob/master/tasks/converter/less_conversion.rb
[version]: https://github.com/twbs/bootstrap-sass/blob/master/lib/bootstrap-sass/version.rb
[contrib]: https://github.com/twbs/bootstrap-sass/graphs/contributors
[antirequire]: https://github.com/twbs/bootstrap-sass/issues/79#issuecomment-4428595
[jsdocs]: http://getbootstrap.com/javascript/#transitions
Thomas Park's avatar
Thomas Park committed
350
[sass-precision]: http://sass-lang.com/documentation/Sass/Script/Value/Number.html#precision%3D-class_method
Corey Sewell's avatar
Corey Sewell committed
351
352
[mincer]: https://github.com/nodeca/mincer
[autoprefixer]: https://github.com/ai/autoprefixer