Jekyll/Old Crap

This page covers my adventure in getting a Jekyll site set up.

My intent in using Jekyll was to set up a site that would host a pile of Markdown files that compose the contents of a book. Thus, the site is mainly content, and not many blog posts.

I'm writing up my procedure in the spirit of this thread: https://github.com/jekyll/jekyll/issues/1650

Creating Jekyll Site

Here's the basics of setting up a Jekyll site in a Github repository.

Also see here: https://help.github.com/articles/using-jekyll-with-pages

Installing Ruby

First thing you'll need is a computer with a version of ruby on it.

Installing Ruby on Mac OS X

To install Ruby on Mac OS X, I had to first install ruby-build, then install rbenv.

One way to install these is using Homebrew:

brew install ruby-build rbenv

Installing Ruby Just About Anywhere

Alternatively, you can use sstephenson's Github projects, ruby-build and rbenv:

• rbenv: https://github.com/sstephenson/rbenv - this project helps you manage Ruby installations
• ruby-build: https://github.com/sstephenson/ruby-build - this project helps you build Ruby

git clone https://github.com/sstephenson/rbenv.git ~/.rbenv
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bash_profile
echo 'eval "$(rbenv init -)"' >> ~/.bash_profile

then start a new shell and make sure this command prints a function:

type rbenv

Now install ruby-build as a plugin to rbenv:

git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build

Finally, you can install a version of Ruby:

$ rbenv install -l # list all available versions
$ rbenv install 2.0.0-p247 # install a particular version

Once you've installed Ruby, you can move on to installing Jekyll.

Setting Up Jekyll Githug Pages Site

The way we're going to use Ruby and Jekyll is by creating a bundle of gems. These ruby gems perform some core functionality, so a bundle of gems is a way of providing you with lots of different tools for turning your raw site content into polished static web content.

Make Yer Bundle

Install the bundler, which will help us create gem bundles:

gem install bundler

Now you can create a Gemfile that tells ruby what gems this bundle will need. It should contain the following contents:

source 'https://rubygems.org'
gem 'github-pages'

When I tried to install the bundle using this command,

$ bundle install
Fetching gem metadata from https://rubygems.org/.........
Fetching additional metadata from https://rubygems.org/..
Resolving dependencies...

An error occurred while installing RedCloth (4.2.9), and Bundler cannot
continue.
Make sure that `gem install RedCloth -v '4.2.9'` succeeds before bundling.

So I ran that gem install command, which installed a bunch of dependent gems. Then I ran the command again:

$ bundle install
Using RedCloth 4.2.9
Using i18n 0.6.9
Using json 1.8.1
[...]
Using jekyll 1.5.1
[...]
Using kramdown 1.3.1
Using rdiscount 2.1.7
Using github-pages 17
Using bundler 1.6.1
Your bundle is complete!
Use `bundle show [gemname]` to see where a bundled gem is installed.

Okay, we've successfully made our gem bundle.

Check Out Your Site Repo

Next step is to check out a copy of the repo where you want your site to go, using git clone:

git clone <your repo here>

Next, switch to the gh-pages branch, which is the branch that contains the live content for your site:

git checkout --orphan gh-pages

This will create a new branch called gh-pages that is an orphan, i.e., distinct and separate from any other branch (that way, it doesn't try to pull in changes to other branches).

Now create your Jekyll site with the new command:

jekyll new /path/to/repo

Now your basic, barebones Jekyll site should be complete and ready-to-serve. Try serving it up with Jekyll locally:

jekyll serve

This command will force Jekyll to generate new static content from all of the raw markdown and other content that composes your site. Now see it live by pointing your browser to 0.0.0.0:4000. You should see something like this:

The pages you see are being hosted in the _site directory in your repository.