kotovalexarian-likes-github/twbs--bootstrap
1
0
Fork 0
mirror of https://github.com/twbs/bootstrap.git synced 2022-11-09 12:25:43 -05:00
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

Browse source
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 layout: page
title: Compiling title: Build tools
group: getting-started 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 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:
{:toc}
## Install Grunt 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`.
**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. 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.
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.
When completed, you'll be able to run the various Grunt commands provided from the command line. 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/ [install-ruby]: https://www.ruby-lang.org/en/documentation/installation/
[gembundler]: http://bundler.io/ [gembundler]: http://bundler.io/
## Available Grunt commands ## Using Grunt
Our Gruntfile includes the following commands and tasks:
| Task | Description | | 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 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. | | `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]. * `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. 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 [libsass]: https://github.com/sass/libsass
[grunt-sass]: https://github.com/sindresorhus/grunt-sass [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`. Should you encounter problems with installing dependencies or running Grunt commands, uninstall all previous dependency versions (global and local). Then, rerun `npm install`.