move compilting to build-tools, rewrite some grunt stuff, add local docs with jekyll...

diff --git a/docs/getting-started/compiling.md b/docs/getting-started/build-tools.md
similarity index 52%
rename from docs/getting-started/compiling.md
rename to docs/getting-started/build-tools.md
index 46c3b0f2d7bd92deb094b93f96b6e25306679830..9d91dbe1180c46e66ec290dddece79c7433e44a2 100644 (file)
--- a/docs/getting-started/compiling.md
+++ b/docs/getting-started/build-tools.md
@@ -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`.