Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Convert docs to Jekyll #6925

Merged
merged 22 commits into from

10 participants

@mdo
Owner

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 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. 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?

@lukeman

This is great—the pros certainly outweigh the cons. I've enjoyed the ease of just browsing development docs locally, but the previous build system was just strange enough that I never felt comfortable helping out on the docs side.

@cvrebert
Owner

:thumbsup: Makes it easier for a pure vanilla user (who doesn't compile/minify the less/JS themselves) to submit a docs patch. Ruby comes preinstalled on most *nix boxes; the same cannot be said for nodejs.

@boulox

+1 for jekyll.

I can see already how many question you gonna get on how to run a jekyll server locally.

@xcash

Sphinx is also very good and readthedocs pulls/compile from GHbut but it's in the python ecosystem . So +1 for Jekyll

@polymetis

For the markdown problem it might be a good idea to switch Jekyll's markdown engine to Kramdown because it has pretty nifty block and inline attributes.

Haven't been through through all the docs in their raw form but I think that should help with the custom html problem at least a bit.

@ghedwards

Why not stick with a node / js solution, node / javascript is much more developer platform friendly.

@mdo
Owner

Why not stick with a node / js solution, node / javascript is much more developer platform friendly.

@ghedwards I think that's definitely true for building components, but managing the docs has been rather cumbersome these last few months. Releasing as I outlined above is a pain, too, and full of arcane copy-paste scripts. With Jekyll, we build on the GitHub platform to offload a lot of the work.

It's one extra command to run to see the docs, but ultimately worth it I think.

@ghedwards

Does it require someone wishing to compile an extension of the documentation in their own fork to install Ruby?

@mdo
Owner

Does it require someone wishing to compile an extension of the documentation in their own fork to install Ruby?

Ruby is required, yes, but as @cvrebert mentioned, Ruby is often already available to many developers.

@ghedwards

You mention that Github supports Jekyll? Does this mean you can commit the Jekyll files and github will compile them for you?

@mdo
Owner

@ghedwards Yes, that's exactly how it works. Instead of our crazy makefile build script, we just push to the gh-pages branch and GitHub Pages does all the work.

@mdo
Owner

I've finished converting all the Prettify code includes into Pygments sections. Much simpler HTML, CSS, and JS now that things don't need escaping. Still need to look into inline <code> elements though as those are still escaped.

Also included in the update is an updated makefile (since we don't need to compile the Mustache files) with a new output. Should feel a bit brighter (yay color!), yet more streamlined.

makefile-output

@mdo mdo merged commit aa5f090 into 3.0.0-wip
@mdo mdo deleted the bs3_jekyll branch
@boulox boulox referenced this pull request
Merged

WIP: Bootstrap 3 #6342

120 of 126 tasks complete
@dudebout

The behavior is still wrong. The check appears at the same time as the task is finished. Why don't you guys use #6576?

Owner

This was only an update to reflect the changes introduced into v3 with the switch the Jekyll. We'll continue to look into improving the makefile as development continues.

But #6576 got closed because the commit was not read and it fixes a real issue.

Owner

I understand that, and we'll circle back around to it when we're ready to. We've got a long list of things to do with v3 and many of them are easier and less fussy to knock out than makefiles (at least, for me). We'll get there.

This is exactly why I volunteered my time to figure it out and put it in a pull request. I won't bother you guys anymore about this.

Owner

I understand that, but we still have to review everything that comes in and test it as much as we can. I understand your pull request was likely closed prematurely, and I appreciate the effort you've put into this, but the simple matter is we'll get to it when we can.

@rejithomas

Tried compiling the documentation with Jekyll, and ended up with "Liquid Exception: incompatible character encodings: Windows-1252 and UTF-8 in css.html"

Do i need to re-install Jekyll or change encoding settings?

@StevenBlack

@rejithomas Issue the following command once on your terminal session, before calling Jekyll

chcp 65001

@rejithomas

Terminal returns to command prompt, after chcp and calling Jekyll. No error messages. Jekyll doesn't compile.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 12, 2013
  1. @mdo

    nuke dat extend docs page

    mdo authored
  2. @mdo

    convert to jekyll

    mdo authored
  3. @mdo

    nuke what we don't need for jekyll

    mdo authored
  4. @mdo
  5. @mdo

    rearrange jekyll and docs

    mdo authored
Commits on Feb 13, 2013
  1. @mdo
  2. @mdo

    update makefile to work again; gitignore the compiled docs _gh_pages …

    mdo authored
    …folder; test makefile with darkened navbar active bg
  3. @mdo
  4. @mdo
Commits on Feb 14, 2013
  1. @mdo

    readme improvements

    mdo authored
  2. @mdo
  3. @mdo
  4. @mdo
  5. @mdo

    twerk dat manni pygment style

    mdo authored
  6. @mdo
Commits on Feb 15, 2013
  1. @mdo

    Specify new local URL

    mdo authored
  2. @mdo
  3. @mdo
  4. @mdo
  5. @mdo

    Update makefile

    mdo authored
  6. @mdo
  7. @mdo
Something went wrong with that request. Please try again.