As all of you may have noticed the theme has changed and the URL seems to have been redirected to Github. I decided to try out this github pages thing and it seems to work pretty well. The static content idea is really attractive to me and really gives me much more power over the pages with a small tradeoff for convenience. But convenience is a non-issue for most programmers who can write tools to make the inconvenient convenient.

What I want to talk about here is actually how I started doing this and why I ended up moving my blog across, along with what I learned along the way about Jekyll-Bootstrap, Octopress, Jekyll, the annoying problems and the process of migrating from a WordPress blog to a Octopress/Disqus duo.

1. Github Pages

After a friend of mine started up his blog, I decided to give it a shot too. From searching around most of the Github pages around were set up as blogs. It seemed like that was a natural thing to do so I went on and used the Github automatic page generator.

The themes provided were incredibly high quality, and were easy to read on the iPhone. The syntax highlighting seemed to just work too so it seemed like everything was going to be good.

I soon realized that all the automatic page generator did was set up an index.html on the repository. I had to begin editing the html page myself and if I wanted an automatically updated sidebar of pages and posts, there needed to be some Liquid code in the pages that required that.

It started to seem like a pain for a blogging environment.

2. Jekyll-bootstrap

Believing in the power of existing tools, I was sure someone out there would have solved this problem for me. After googling around I found Jekyll-Bootstrap. It seemed fairly simple to set up, since it was simply a starting point with Rakefiles and preset templates for blogging. It also used pygments for syntax highlighting, and had theming support and plugins.

1
2
3

$ rake new_post title="Rants of today"
$ rake new_page title="My new page"
$ rake preview

You had to have an empty repository to start with Jekyll-bootstrap because it needs to dictate how things are in your blog. The easiest way to do this it seems is to begin your repository contents with the contents of Jekyll-bootstrap.

1
2
3
4

$ git clone https://github.com/plusjade/jekyll-bootstrap.git USERNAME.github.com
$ cd USERNAME.github.com
$ git remote set-url origin git@github.com:USERNAME/USERNAME.github.com.git
$ git push origin master

The site, being a set of markdown and html files with Liquid markups would then simply be checked in to github where it would automatically be run through Jekyll and displayed.

The themes for Jekyll-bootstrap weren’t as good as the ones you could find for Github, but that did not pose much of a problem. There also weren’t many of them. It also turned out that besides the automatic page and post file generation and theme application, there wasn’t much in terms of defaults. The index.md only had a simple example of listing posts, and if you wanted a sidebar and show posts on the index.html, or apply disqus to it, you had to do all of that yourself.

Jekyll-bootstrap Themes

1

$ rake theme:install git="https://github.com/dhulihan/hooligan.git"

I was surprised at the seeming lack of extra examples that can be copy-pasted in to set the blog up. As it turns out jekyll-bootstrap hasn’t been maintained for a while, since its maintainer has moved on to create another static site generator.

I set this aside on a different folder and proceeded to try the other alternative which seemed more used and still had an active community and maintainers.

3. Octopress

The alternative was Octopress. Octopress is different from Jekyll-bootstrap in the sense that it wasn’t just a template for blogging sites. It is a small collection of tools that allow you to set themes and generate your site locally. Another difference is that the static site generation is actually done on your own PC, and you push the result to github. This means it would work for any other site, which was fairly attractive. Similar to Jekyll-bootstrap, you would fork Octopress and clone your modifications in to another repository, and not your site.

1
2
3
4
5
6
7
8
9
10
11
12
13

$ git clone git://github.com/davidsiaw/octopress.git Octopress   # from my forked repository
$ cd octopress
$ gem install bundler
$ rbenv rehash
$ bundle install        # prepares the set of tools required to maintain your site
$ rake install          # generates your site's bootstrap sources

$ rake generate
$ rake deploy           # automatically creates a _deploy folder and pushes that to your site

$ git add .             # add the created sources and sass folders that contain the real sources for your site
$ git commit -m "update sources"
$ git pushes            # push your site's sources

Octopress also has a much larger set of themes available to use to customize your site. Like Jekyll-bootstrap, the theme is on a github repository that you can clone and install with.

Octopress Theme Site

One big headache with Octopress was that its syntax highlighting was not part of the theme, and that the default theme was the Solarize theme which was fairly ugly and bluish. It also wasn’t straightforward to configure. It turned out that the syntax configuration is in sass/syntax.scss and the variables in it are stored in sass/solarized.scss.

In order to solve this problem, some googling turned up some people solving this issue by switching the markdown generator to CodeRay. But it did not change the theme for me and it seemed like a very messy change to have, so I decided to roll my sleeves up and edit the scss files myself, which came out pretty well.

4. Wordpress Migration

The final part of my blog setup was to see if I could transfer all the data from my old WordPress blog to this one. It turns out I could. Jekyll had a set of tools that allowed me to import the XML file produced by the WordPress export function. This automatically added the pages to source/pages and posts to source/posts in html format.

This is not desirable because in HTML format the newlines are ignored and the posts look fairly retarded, so I renamed all the extensions to .md.

1
2
3
4

$ gem install jekyll-import --pre
$ gem install hpricot
$ ruby -rubygems -e 'require "jekyll/jekyll-import/wordpressdotcom";
    JekyllImport::WordpressDotCom.process({ :source => "wordpress.xml" })'

However, the export was far from perfect. My WordPress install used a lot of plugins, meaning the content was littered with shortcodes that did not look like part of any content. I had to touch nearly every generated file that was imported to get everything nice and polished again.

5. Disqus

Disqus is a hosted commenting system that provides a very nice commenting theme that blends in to most Jekyll sites, that’s the sole reason I chose it. I thought facebook comments were nice and would provide me with more exposure but it just looked ugly.

Setting Disqus up was fairly easy. It involved registering on Disqus and adding the shortcode of Disqus to the _config.yml. There was one very undocumented frustration though, the comments were not showing up. It turns out that instead of having trailing ‘/’ on the URLs like other people who had this problem, the imported posts had no ‘comments: true’ line on them! This meant Disqus was disabled for all those posts. I had to then go through all of the posts and add comments to enable Disqus.

Importing the Wordpress comments into Disqus was fairly trivial as there was a Disqus plugin for Wordpress that allowed us to pull all of the Wordpress plugins in. In addition, I could then rename the domains on all the comments that were associated with the Wordpress site to being associated to my site, which was a really handy tool to have.

Conclusion

Overall, this actually took an entire Saturday morning, which is pretty heavy for a “Simple” framework for blogging on static sites. The only thing that looked simple was the amount of stuff that you end up with on the website, which gives the impression that not a lot of work went into building the site.

I guess it wouldn’t be too far fetched to say that even with top grade tools, if a little customization is required, the amount of work to set up a website increases exponentially in relation to the customization you do.

With blogging on the site, one of the things I miss is the ability to see images next to the text that I type, that Wordpress’s web interface or Bunnyblogger affords.