Lots of updates
This commit is contained in:
baldo
parent
e3cfff8310
commit
39e7af6238
454 changed files with 221168 additions and 36622 deletions
|
|
@ -1,11 +1,21 @@
|
|||
# Bootstrap for Sass [](http://badge.fury.io/rb/bootstrap-sass) [](http://badge.fury.io/bo/bootstrap-sass-official) [](http://travis-ci.org/twbs/bootstrap-sass)
|
||||
# Bootstrap for Sass
|
||||
[](http://badge.fury.io/rb/bootstrap-sass)
|
||||
[](https://www.npmjs.com/package/bootstrap-sass)
|
||||
[](http://badge.fury.io/bo/bootstrap-sass)
|
||||
[](https://travis-ci.org/twbs/bootstrap-sass)
|
||||
|
||||
`bootstrap-sass` is a Sass-powered version of [Bootstrap](http://github.com/twbs/bootstrap), ready to drop right into your Sass powered applications.
|
||||
`bootstrap-sass` is a Sass-powered version of [Bootstrap](https://github.com/twbs/bootstrap) 3, ready to drop right into your Sass powered applications.
|
||||
|
||||
This is Bootstrap 3. For Bootstrap 4 use the [Bootstrap Ruby gem](http://github.com/twbs/bootstrap-rubygem) if you use Ruby, and the [main repo](http://github.com/twbs/bootstrap) otherwise.
|
||||
|
||||
## 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.
|
||||
|
|
@ -13,66 +23,104 @@ Please see the appropriate guide for your environment of choice:
|
|||
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
|
||||
gem 'bootstrap-sass', '~> 3.2.0'
|
||||
gem 'bootstrap-sass', '~> 3.3.6'
|
||||
gem 'sass-rails', '>= 3.2'
|
||||
```
|
||||
|
||||
It is also recommended to use [Autoprefixer](https://github.com/ai/autoprefixer-rails) with Bootstrap
|
||||
to add browser vendor prefixes automatically. Simply add the gem:
|
||||
|
||||
```ruby
|
||||
gem 'autoprefixer-rails'
|
||||
```
|
||||
|
||||
`bundle install` and restart your server to make the files available through the pipeline.
|
||||
|
||||
In `app/assets/stylesheets/application.css.scss`:
|
||||
Import Bootstrap styles in `app/assets/stylesheets/application.scss`:
|
||||
|
||||
```scss
|
||||
// "bootstrap-sprockets" must be imported before "bootstrap" and "bootstrap/variables"
|
||||
@import "bootstrap-sprockets";
|
||||
@import "bootstrap";
|
||||
```
|
||||
|
||||
Do not use `//= require` in Sass or your other stylesheets will not be [able to access][antirequire] the Bootstrap mixins or variables.
|
||||
`bootstrap-sprockets` must be imported before `bootstrap` for the icon fonts to work.
|
||||
|
||||
In `app/assets/javascripts/application.js`:
|
||||
Make sure the file has `.scss` extension (or `.sass` for Sass syntax). If you have just generated a new Rails app,
|
||||
it may come with a `.css` file instead. If this file exists, it will be served instead of Sass, so rename it:
|
||||
|
||||
```console
|
||||
$ mv app/assets/stylesheets/application.css app/assets/stylesheets/application.scss
|
||||
```
|
||||
|
||||
Then, remove all the `*= require_self` and `*= require_tree .` statements from the sass file. Instead, use `@import` to import Sass files.
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
#### Rails 3.2.x
|
||||
`bootstrap-sprockets` and `bootstrap` [should not both be included](https://github.com/twbs/bootstrap-sass/issues/829#issuecomment-75153827) in `application.js`.
|
||||
|
||||
Rails 3.2 is [no longer maintained for bugfixes](http://guides.rubyonrails.org/maintenance_policy.html), and you should upgrade as soon as possible.
|
||||
`bootstrap-sprockets` provides individual Bootstrap Javascript files (`alert.js` or `dropdown.js`, for example), while
|
||||
`bootstrap` provides a concatenated file containing all Bootstrap Javascripts.
|
||||
|
||||
Starting with bootstrap-sass v3.1.1.1, due to the structural changes from upstream you will need these
|
||||
backported asset pipeline gems on Rails 3.2. There is more on why this is necessary in
|
||||
https://github.com/twbs/bootstrap-sass/issues/523 and https://github.com/twbs/bootstrap-sass/issues/578.
|
||||
#### Bower with Rails
|
||||
|
||||
When using [bootstrap-sass Bower package](#c-bower) instead of the gem in Rails, configure assets in `config/application.rb`:
|
||||
|
||||
```ruby
|
||||
gem 'sprockets-rails', '=2.0.0.backport1'
|
||||
gem 'sprockets', '=2.2.2.backport2'
|
||||
gem 'sass-rails', github: 'guilleiguaran/sass-rails', branch: 'backport'
|
||||
# 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
|
||||
config.assets.precompile << %r(bootstrap-sass/assets/fonts/bootstrap/[\w-]+\.(?:eot|svg|ttf|woff2?)$)
|
||||
# Minimum Sass number precision required by bootstrap-sass
|
||||
::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
|
||||
```
|
||||
|
||||
Replace Bootstrap `@import` statements in `application.scss` with:
|
||||
|
||||
```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
|
||||
|
||||
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.
|
||||
|
||||
### b. Compass without Rails
|
||||
|
||||
Install the gem
|
||||
```sh
|
||||
gem install bootstrap-sass
|
||||
Install the gem:
|
||||
|
||||
```console
|
||||
$ gem install bootstrap-sass
|
||||
```
|
||||
|
||||
If you have an existing Compass project:
|
||||
|
||||
```ruby
|
||||
# config.rb:
|
||||
require 'bootstrap-sass'
|
||||
```
|
||||
1. Require `bootstrap-sass` in `config.rb`:
|
||||
|
||||
```console
|
||||
$ bundle exec compass install bootstrap
|
||||
```
|
||||
```ruby
|
||||
require 'bootstrap-sass'
|
||||
```
|
||||
|
||||
2. Install Bootstrap with:
|
||||
|
||||
```console
|
||||
$ bundle exec compass install bootstrap -r bootstrap-sass
|
||||
```
|
||||
|
||||
If you are creating a new Compass project, you can generate it with bootstrap-sass support:
|
||||
|
||||
|
|
@ -89,31 +137,29 @@ $ 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.erb) - all of Bootstrap variables, override them here.
|
||||
* [_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
|
||||
|
||||
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:
|
||||
bootstrap-sass Bower package is compatible with node-sass 3.2.0+. You can install it with:
|
||||
|
||||
```console
|
||||
$ bower install bootstrap-sass-official
|
||||
$ bower install bootstrap-sass
|
||||
```
|
||||
|
||||
`bootstrap-sass` is taken so make sure you use the command above.
|
||||
|
||||
Sass, JS, and all other assets are located at [assets](/assets).
|
||||
|
||||
By default, `bower.json` main field list only the main `bootstrap.scss` and all the static assets (fonts and JS).
|
||||
By default, `bower.json` main field list only the main `_bootstrap.scss` and all the static assets (fonts and JS).
|
||||
This is compatible by default with asset managers such as [wiredep](https://github.com/taptapship/wiredep).
|
||||
|
||||
#### Node.js Mincer
|
||||
|
||||
If you use [mincer][mincer] with node-sass, import bootstrap into like so:
|
||||
If you use [mincer][mincer] with node-sass, import bootstrap like so:
|
||||
|
||||
In `application.css.ejs.scss` (NB **.css.ejs.css**):
|
||||
In `application.css.ejs.scss` (NB **.css.ejs.scss**):
|
||||
|
||||
```scss
|
||||
// Import mincer asset paths helper integration
|
||||
|
|
@ -137,8 +183,8 @@ See also this [example manifest.js](/test/dummy_node_mincer/manifest.js) for min
|
|||
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`.
|
||||
[`_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
|
||||
|
|
@ -147,21 +193,18 @@ In the application Sass file, replace `@import 'bootstrap'` with:
|
|||
|
||||
#### Sass: Number Precision
|
||||
|
||||
bootstrap-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][sass-precision] of 10 (default is 5).
|
||||
bootstrap-sass [requires](https://github.com/twbs/bootstrap-sass/issues/409) minimum [Sass number precision][sass-precision] of 8 (default is 5).
|
||||
|
||||
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
|
||||
::Sass::Script::Number.precision = [10, ::Sass::Script::Number.precision].max
|
||||
::Sass::Script::Value::Number.precision = [8, ::Sass::Script::Value::Number.precision].max
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
||||
#### Sass: Autoprefixer
|
||||
|
||||
Using [Autoprefixer][autoprefixer] with Bootstrap is recommended.
|
||||
Bootstrap requires the use of [Autoprefixer][autoprefixer].
|
||||
[Autoprefixer][autoprefixer] adds vendor prefixes to CSS rules using values from [Can I Use](http://caniuse.com/).
|
||||
|
||||
#### JavaScript
|
||||
|
|
@ -209,7 +252,7 @@ When using bootstrap-sass with Compass, Sprockets, or Mincer, you **must** impor
|
|||
|
||||
### Sass
|
||||
|
||||
Import Bootstrap into a Sass file (for example, application.css.scss) to get all of Bootstrap's styles, mixins and variables!
|
||||
Import Bootstrap into a Sass file (for example, application.scss) to get all of Bootstrap's styles, mixins and variables!
|
||||
|
||||
```scss
|
||||
@import "bootstrap";
|
||||
|
|
@ -231,6 +274,27 @@ $navbar-default-color: $light-orange;
|
|||
@import "bootstrap";
|
||||
```
|
||||
|
||||
## Version
|
||||
|
||||
Bootstrap for Sass version may differ from the upstream version in the last number, known as
|
||||
[PATCH](http://semver.org/spec/v2.0.0.html). The patch 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.6 | 3.3.6 |
|
||||
| 3.3.5 | 3.3.5 |
|
||||
| 3.3.4 | 3.3.4 |
|
||||
| 3.3.2 | 3.3.3 |
|
||||
| <= 3.3.1 | 3.3.1.x |
|
||||
|
||||
Always refer to [CHANGELOG.md](/CHANGELOG.md) when upgrading.
|
||||
|
||||
---
|
||||
|
||||
## Development and Contributing
|
||||
|
|
@ -257,7 +321,7 @@ To convert a specific branch or version, pass the branch name or the commit hash
|
|||
The latest converter script is located [here][converter] and does the following:
|
||||
|
||||
* Converts upstream bootstrap LESS files to its matching SCSS file.
|
||||
* 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`.
|
||||
* 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`.
|
||||
* Copies all upstream font files into `assets/fonts/bootstrap`.
|
||||
* Sets `Bootstrap::BOOTSTRAP_SHA` in [version.rb][version] to the branch sha.
|
||||
|
||||
|
|
@ -278,15 +342,15 @@ 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
|
||||
[Diaspora](http://diasporaproject.org/), [rails_admin](https://github.com/sferik/rails_admin),
|
||||
Michael Hartl's [Rails Tutorial](http://railstutorial.org/), [gitlabhq](http://gitlabhq.com/) and
|
||||
[kandan](http://kandanapp.com/).
|
||||
[Diaspora](https://diasporafoundation.org/), [rails_admin](https://github.com/sferik/rails_admin),
|
||||
Michael Hartl's [Rails Tutorial](https://www.railstutorial.org/), [gitlabhq](http://gitlabhq.com/) and
|
||||
[kandan](http://getkandan.com/).
|
||||
|
||||
[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
|
||||
[sass-precision]: http://sass-lang.com/documentation/Sass/Script/Number.html#precision-class_method
|
||||
[sass-precision]: http://sass-lang.com/documentation/Sass/Script/Value/Number.html#precision%3D-class_method
|
||||
[mincer]: https://github.com/nodeca/mincer
|
||||
[autoprefixer]: https://github.com/ai/autoprefixer
|
||||
[autoprefixer]: https://github.com/postcss/autoprefixer
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue