This article aims to provide a compact tutorial for setting up an Octopress blog from scratch on OSX.

Since so many people encounter Mountain Lion breakage, the article starts with a few pointers how to get Homebrew, Git, make, Ruby going first.

Please look closely at the steps if you really want to do each of them. For instance I replace rvm with rbenv, you may want to skip that.

  • Replace with your domain name everywhere.
  • Replace kvz with your Github username everywhere.

Upgraded to Mountain Lion?

Make sure you can build something again

  • Upgrade Xcode
  • Launch Xcode
  • Select Xcode -> Preferences from the menu bar.
  • Select the Downloads tab.
  • Install "Command Line Tools".

"Boots into OS X, and my terminal takes FOREVER to boot. Fixing permissions on the /usr/local directory fixed most of that"

$ sudo chown -R `whoami` /usr/local

Fixing Homebrew

$ brew update
$ brew outdated|xargs brew install
$ brew tap homebrew/dupes
$ brew install apple-gcc42 git
$ brew upgrade

Switch from rvm to rbenv

Remove rvm

$ rvm implode

Install rbenv instead, and Ruby 1.9.3-p194 which is required for Octopress

$ brew install rbenv
$ brew install ruby-build
$ eval "$(rbenv init -)"
$ rbenv install 1.9.3-p194
$ rbenv global 1.9.3-p194


This should be in your ~/.bash_profile, ~/.zshrc or ~/.zprofile

$ export PATH="$HOME/.rbenv/bin:$PATH"
$ eval "$(rbenv init -)"
$ # required for
$ export LC_CTYPE=en_US.UTF-8
$ export LANG=en_US.UTF-8

Source it now so you won't have to open another tab first

$ source ~/.zprofile || source ~/.zshrc || source ~/.bash_profile

Make sure you have no other Ruby versions in your $PATH

$ echo "# ${PATH}"
$ # /Users/kevin/.rbenv/shims:/Users/kevin/.rbenv/bin:/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin

e.g., mine had a legacy /Users/kevin/.gem/ruby/1.8/bin in it, causing Jekyll to segfault.

Installing Octopress as Your Blog

$ git clone git://
$ cd
$ ruby --version # should read ruby 1.9.3p194 (2012-04-20 revision 35410) [x86_64-darwin12.2.0]
$ gem install bundler
$ rbenv rehash
$ bundle install

Deploying to Github project pages ([gh-pages])

Let octopress know about this

$ rake setup_github_pages
$ # Repository url:
$ rake install
$ rake generate && rake deploy

Note: Different from Github use pages ([master]).

Setup a domain

$ echo '' > source/CNAME

Put these DNS records in place

A     record from     to  (Cannot be a CNAME!)
CNAME record from to


So you'll only have to type make blog to push online ALL THE THINGS!

Edit ./Makefile

all: tweets dependencies blog

	bundle exec rake setup_github_pages\[\]

	fgrep -rIi "permalink: false" ./source/_posts | awk -F: '{print "$EDITOR " $$1}' |bash

	bundle exec rake twitter
	make blog MSG="updated twitter"

	rake build_comments

	(cd ~/workspace/ 2>/dev/null || (cd ~/workspace && git clone && git pull
	(cd ~/workspace/bash3boilerplate 2>/dev/null || (cd ~/workspace && git clone && git pull
	(cd ~/workspace/dotfiles 2>/dev/null || (cd ~/workspace && git clone && git pull
	(cd ~/workspace/transloadit-api2 2>/dev/null || (cd ~/workspace && git clone && git pull
	(cd ~/workspace/nsfailover 2>/dev/null || (cd ~/workspace && git clone && git pull
	(cd ~/workspace/logstreamer 2>/dev/null || (cd ~/workspace && git clone && git pull

	bundle exec rake build && bundle exec rake generate && bundle exec rake preview

	git pull && \
	bundle install && \
	bundle exec rake integrate && \
	bundle exec rake build && \
	bundle exec rake generate && \
	bundle exec rake deploy && \
	git add .; \
	git commit -am "blog update $$(date +%Y-%m-%d)"; \
	git push origin master

.PHONY: blog%

Don't forget to commit the source for your blog.

To add your project's master as the new origin. This is what my .git/config looks like:

  repositoryformatversion = 0
  filemode = true
  bare = false
  logallrefupdates = true
  ignorecase = true
[remote "origin"]
  fetch = +refs/heads/*:refs/remotes/origin/*
  url =
[remote "octopress"]
  url = git://
  fetch = +refs/heads/*:refs/remotes/octopress/*
[branch "master"]
  remote = origin
  merge = refs/heads/master

This way you can pull from octopress/master to receive updates, and push to origin/master to save your posts.

Start Blogging

New article

$ rake new_post\["Blog with Octopress"\]
$ $EDITOR source/_posts/$(date +%Y-%m-%d)


Add an About Page

Add & edit like so

$ rake new_page\[about\]
$ $EDITOR source/about/

Add a link to it in the navigation

$ $EDITOR source/_includes/custom/navigation.html

Add an About Panel

$EDITOR source/_includes/custom/asides/about.html

and now add it to your _config.yml so it will be included on every page:

  - custom/asides/about.html

More info

Bombs Away :)

$ make blog MSG="Updated blog"