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, and 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 tocp
directories into another copy of the Bootstrap repo checked out to thegh-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. Edit: This isn't entirely doable as mixing our custom HTML for the docs with Markdown would yield some odd formatting problems, but we'll deal with that when it comes to it.
- Pygments code highlighting. I don't mind Prettify, but the less JavaScript we include, the better as far as I'm concerned. This also means no more escaping HTML tags—a huge huge huge win.
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.
- Mixing HTML and Markdown can get tricky. We have lots of custom HTML, and I'm unsure if we'll run into issues once we start to Markdown-ify page content.
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?