My First Rubygem

Forks and Branches and Commits and stuff...

Earth Date 2009.12.01

Posted by Rich Wheadon | Permalink

Today I finished making a fork of jekyll that allows me to generate my static sites with a context of my choosing from the command line. This became really important to me when starting to generate RSS feeds for my blog. If you haven’t used jekyll then you might check out the wiki and see if it is useful to you. I like Jekyll because it allows me to focus on blogging into a really simple interface… a text editor!!! Additionally it’s really easy to host since there’s no database or dynamic interface to host and worry about, everything is static. Jekyll regenerates the entire site every time you publish it.

Enough about that for now though, if you are reading this post I trust you can go clamber about the web researching Jekyll on your own. My problem was RSS. I didn’t care much for going into the config.yml file every time I wanted to publish a test or production site, but without setting the url: parameter I had no way of pulling the correct value into site.url so as to differentiate between “http://localhost:4000/feed.xml” and “”. So I thought it through with a buddy and figured I could just add an option to the command line that let me choose the config file of my choice.

By patching the code something like:

$ jekyll --opt_config _config.developement.yml 

would use my configuration set up for my localhost development and

$ jekyll --opt_config _config.production.yml

would use my configuration set up for my production environment.

Here’s a log of what it took to get it all working

  1. Installed dependencies per jekyll wiki (

  2. Set up my machine for forking the code (

  3. Forked Jekyll (

  4. Branched the Fork “allow_optional_config”

Once I had the source code down local I began making the necessary changes.

I made a simple change to bin/jekyll

opts.on("--opt_config [FILE_NAME]", "Specify an optional .yml config to use rather than _config.yml") do |opt_config|
options['opt_config'] = opt_config unless opt_config.nil?

I made another simple change to lib/jekyll.rb:

config_filename = override['opt_config'] || '_config.yml'
config_file = File.join(source, config_filename )

I updated the patchlevel in VERSION.yml:

:patch: 6  
:minor: 5
:major: 0

I fixed a little versioning bug in test/helper.rb:

gem 'RedCloth', '>= 4.2.1'

At this point I needed to do some testing.
1. Renamed /usr/bin/jekyll to /usr/bin/jekyll2

2. made the symlink to my current changes

3. Errors because Jekyll is installed through rubygems and I will need to “cut a gem”

4. From command I did a cd into my jekyll website project directory and ran “jekyll”. If you have a _config.yml file it should follow those directions, if not the defaults. On my machine this generated the site into the default _site directory and anywhere I had {{ site.url }}{{ post.url }} liquid tags we see something like “/yyyy/mm/dd/title/of/my/blog/post”

5. I created a file called _config.production, this is the version of my site that should be generating fully qualified site urls rather than relative paths. (very important for rss feed files, etc.) Here are some important different settings in my _config.production:
destination: ./_site.production
auto: true
server_port: 4002

6. From command (still in my jekyll website project directory) ran “jekyll –opt_config _config.production”. This created a new directory called _site.production. Now anywhere in the site where templates contained {{ site.url }}{{ post.url }} liquid tags showed something like “”

Now my site generation works with only one debug switch needing to be changed each time I update my site, but my work is far from over. Next I need to make sure my gem is up to snuff and publish it to Gemcutter so that it can be vetted. I also need to get up to speed on Capistrano so that deployment is even easier.