From: Mark Otto Date: Mon, 10 Aug 2015 17:29:35 +0000 (-0700) Subject: move compilting to build-tools, rewrite some grunt stuff, add local docs with jekyll... X-Git-Tag: v4.0.0-alpha~94 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=e839b093a01d9e2059ccfe997801433722af2b33;p=thirdparty%2Fbootstrap.git move compilting to build-tools, rewrite some grunt stuff, add local docs with jekyll section based on readme's more detailed walkthrough --- 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 46c3b0f2d7..9d91dbe118 100644 --- 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 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`.