Octopress is a static blog generator. It uses Jekyll which was created by Github to run Github Pages and now I’m using it to power my re-launched blog.

I’m attracted by the prospect of using Octopress because it’s dead simple. It generates the blog content as flat pages so it’s super fast. It allows me to write using Markdown and deploy via Git.

There’s no server setup and no hosting fees, as it’s hosted using Github Pages. Also it’s written in Ruby, so it works with all the tools I’m familiar with.

What follows is more for my reference than anything, so I can remember how I set things up.

Initial setup

Create a new Github repo named yourgithubusername.github.io.

The name is important here as Github Pages will automatically find this repo and serve up the content it finds in the master branch as your website at http://yourgithubusername.github.io.

Grab Octopress and change directory:

$ git clone git://github.com/imathis/octopress.git yourgithubusername.github.io
$ cd yourgithubusername.github.io

Octopress has its’ own rvmrc file, but I like to use gemsets, so I created my own before installing bundler and the required gems:

$ rvm use 1.9.3@yourgemsetname --create --rvmrc
$ gem install bundler
$ bundle install

Install the default theme:

$ rake install

Octopress has a configuration rake task that automatically sets the repo up for easy deployment to Github Pages:

$ rake setup_github_pages

This task does quite a few things. The most important is that it creates a new _deploy directory that is another git repository. This is where Octopress generates the flat website for deployment to the master branch of your repo on Github.

All the Octopress code used to generate the website into the _deploy directory now lives in new branch called source. Note in the source branch the .gitignore includes _deploy so it doesn’t get committed in two places!

This sounds more complicated than it is, Octopress has rake tasks to make this really easy to manage. It’s worth pushing up at this point to check everything works before tinkering:

$ rake generate
$ rake deploy

This copies the generated files into _deploy, adds them to git, commits and pushes them up to the master branch.

Visit http://yourgithubusername.github.io

Note at this point only the website has been committed, the source needs to be comitted separately via:

$ git add .
$ git commit -m 'Initial source commit'
$ git push origin source

Running Octopress locally

The simplest thing to do is fire up your site on http://localhost:4000 via:

$ rake preview

Alternatively, Octopress works really well with POW server.

$ cd ~/.pow
$ ln -s /path/to/your/octopress/site yoursitename

Now that you’re setup with POW, in the root of your source branch run:

$ rake watch

Load up http://yoursitename.dev

Theme customisation

I’m using the ‘Whitespace’ theme by lucaslew. Other themes are available.

I’ve tweaked the header to remove the search and include navigation links to my Twitter and Github accounts.

I installed the theme by running the following in the root of the source branch. Say yes when it asks you to overwrite existing files.

$ git clone git://github.com/lucaslew/whitespace.git .themes/whitespace
$ rake install['whitespace']
$ rake generate

_config.yml

This is where the main site configuration lives. Things like the blog title and various 3rd Party Settings, your Twitter and Github handles etc.

Changes to _config.yml will require you to restart the rake watch task if you’re using POW server.

Creating this post

As easy as:

rake new_post["Hello Octopress and Github pages"]

Deploying to Github Pages

$ rake generate
$ rake deploy

Just rememeber to manually commit changes made in the source branch.

Custom domain

Github have full details on how to do this in their GitHub Pages Documentation.

Inside your source branch run the following:

echo 'your-domain.com' >> source/CNAME

Regenerate your site and deploy up to Github. In your DNS settings point an A record (for your naked domain) to 204.232.175.78.

For www just point a CNAME record to yourgithubusername.github.io

Working from another machine

As the _deploy directory is in the .gitignore, the easiest thing is to clone the source branch and then setup the _deploy branch manually.

$ git clone -b source git@github.com:username/username.github.io.git username.github.io
$ cd username.github.io
$ bundle install
$ mkdir _deploy
$ cd _deploy
$ git init
$ git remote add origin git@github.com:username/username.github.io.git
$ git pull origin master
$ cd ..