twitter/bootstrap — pull request #6925 by mdo (2013-02-14 06:28:09+00:00)
Title: Convert docs to Jekyll

#### Context

Currently Bootstrap's documentation is compiled from Mustache templates with our makefile. This means we have some overhead in our repository: each docs page has two copies, one .mustache and the other .html. This makes contributions via pull requests convoluted and at times confusing. Compiling the docs before pushing kind of sucks.

I would love to improve upon that for [Bootstrap 3](https://github.com/twitter/bootstrap/pull/6342), and [Jekyll](https://github.com/mojombo/jekyll) seems like a decent improvement.

#### Pros
- **Easier, faster docs deployment.** GitHub Pages supports Jekyll, and makes deploying updated documentation super easy. We just push to the `gh-pages` branch and in a few minutes, done. Currently, we have to compile, push, run a script to `cp` directories into another copy of the Bootstrap repo checked out to the `gh-pages` branch. It kind of sucks.
- **We ditch a hell of a lot of code.** Over 17,000 lines to be exact. Since Jekyll compiles the docs on deploy to Pages, and we don't need to store all that stuff in the repo to start, we don't need to track it's changes. We couldn't as easily do the same with Bootstrap because Mustache files don't get compiled on push to Pages.
- **Better templating support.** We wrote our own tools to compile the docs, and right now they're a bit limiting. No easy logic, no multiple layouts, etc. It's not 100% better, but this affords us all those things.
- **Ability to turn everything into Markdown.** Holy crap would this be awesome. All our comments, pull requests, readme, contributing guidelines, and more are written in Markdown. Having those in Markdown in the repo would be a huge advantage over plain HTML.
- **Pygments code highlighting.** I don't mind Prettify, but the less JavaScript we include, the better as far as I'm concerned.

#### Cons
- **Documentation isn't immediately browsable locally.** I'm not too concerned by this though, because getting them is as easy as installing a gem and running `jekyll --server`. Not too much work, and hopefully less confusing than compiling Mustache templates.
- **Change is kind of sucky.** Folks familiar with the project are likely already in our workflow, so I hope they can adapt.
- **Installing a gem and running scripts.** It's extra work, yes, and definitely something we'll need to be sure we document very well.

Overall, this is ready to merge in. It simplifies our deployment workflow, prevents us from tracking changes to duplicate files (via `.gitignore` and Pages), and sets us up for easier maintenance and iteration going forward.

Any thoughts, one way or the other?