kotovalexarian-likes-github
/
twbs--bootstrap
mirror of https://github.com/twbs/bootstrap.git
1
0
Fork 0
Code Releases Activity

move compilting to build-tools, rewrite some grunt stuff, add local docs with jekyll section based on readme's more detailed walkthrough

This commit is contained in:
Mark Otto 2015-08-10 10:29:35 -07:00
parent 510522039b
commit e839b093a0
1 changed files with 26 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/getting-started/compiling.md → docs/getting-started/build-tools.md
View File

@ -1,25 +1,19 @@
---
layout: page
title: Compiling
title: Build tools
group: getting-started
---
Bootstrap uses [Grunt](http://gruntjs.com) for its build system, with convenient methods for working with the framework. It's how we compile our code, run tests, and more.
Bootstrap uses [Grunt](http://gruntjs.com) for its CSS and JavaScript build system and Jekyll for the written documentation. Our Gruntfile includes convenient methods for working with the framework, including compiling code, running tests, and more.
## Contents
## Tooling setup
* Will be replaced with the ToC, excluding the "Contents" header
{:toc}
To use our Gruntfile and run our documentation locally, you'll need a copy of Bootstrap's source files, Node, and Grunt. Follow these steps and you should be ready to rock:
## Install Grunt
**To install Grunt, you must first [download and install node.js](https://nodejs.org/download/)** (which includes npm). npm stands for [node packaged modules](http://npmjs.com/) and is a way to manage development dependencies through node.js.
From the command line:
1. Install `grunt-cli` globally with `npm install -g grunt-cli`.
2. Navigate to the root `/bootstrap` directory, then run `npm install`. npm will look at [package.json](https://github.com/twbs/bootstrap/blob/master/package.json) and automatically install the necessary local dependencies listed there.
3. [Install Ruby][install-ruby], install [Bundler][gembundler] with `gem install bundler`, and finally run `bundle`. This will install all Ruby dependencies, such as Jekyll and Sass linter.
1. [Download and install Node](https://nodejs.org/download), which we use to manage our dependencies.
2. Install the Grunt command line tools, `grunt-cli`, with `npm install -g grunt-cli`.
3. Navigate to the root `/bootstrap` directory and run `npm install` to install our local dependencies listed in [package.json](https://github.com/twbs/bootstrap/blob/master/package.json).
4. [Install Ruby][install-ruby], install [Bundler][gembundler] with `gem install bundler`, and finally run `bundle`. This will install all Ruby dependencies, such as Jekyll and Sass linter.
When completed, you'll be able to run the various Grunt commands provided from the command line.
@ -28,7 +22,9 @@ When completed, you'll be able to run the various Grunt commands provided from t
[install-ruby]: https://www.ruby-lang.org/en/documentation/installation/
[gembundler]: http://bundler.io/
## Available Grunt commands
## Using Grunt
Our Gruntfile includes the following commands and tasks:
| Task | Description |
| --- | --- |
@ -38,12 +34,12 @@ When completed, you'll be able to run the various Grunt commands provided from t
| `grunt docs` | Builds and tests CSS, JavaScript, and other assets which are used when running the documentation locally via `jekyll serve`. |
| `grunt watch` | This is a convenience method for watching just Sass files and automatically building them whenever you save. |
## Use another Sass compiler
## Switching Sass compilers
Bootstrap is compiled with [libsass][libsass] by default. Use another compiler by setting the `TWBS_SASS` environment variable to:
Bootstrap will be compiled with [libsass][libsass] by default, but you can opt into traditional Ruby Sass by setting the `TWBS_SASS` environment variable. Two options are supported:
* `sass` to use [Ruby Sass][ruby-sass] via [grunt-contrib-sass][grunt-contrib-sass].
* `libsass` (default) to use [libsass][libsass] via [grunt-sass][grunt-sass].
* `sass` to use [Ruby Sass][ruby-sass] via [grunt-contrib-sass][grunt-contrib-sass].
For example, run `TWBS_SASS=sass grunt` to test and build Bootstrap with Ruby Sass.
@ -52,6 +48,17 @@ For example, run `TWBS_SASS=sass grunt` to test and build Bootstrap with Ruby Sa
[libsass]: https://github.com/sass/libsass
[grunt-sass]: https://github.com/sindresorhus/grunt-sass
## Troubleshooting dependencies
## Local documentation
Running our documentation locally requires the use of Jekyll, a decently flexible static site generator that provides us basic includes, Markdown-based files, templates, and more. Here's how to get it started:
1. Run through the [tooling setup](#tooling-setup) above to install Jekyll (the site builder) and Rouge (our syntax highlighter).
- **Windows users:** Read [this unofficial guide](http://jekyll-windows.juthilo.com/) to get Jekyll up and running without problems.
2. From the root `/bootstrap` directory, run `jekyll serve` in the command line.
3. Open <http://localhost:9001> in your browser, and voilà.
Learn more about using Jekyll by reading its [documentation](http://jekyllrb.com/docs/home/).
## Troubleshooting
Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`.