Blog with Octopress and Github pages

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 kvz with your Github username everywhere.
Replace kvz.io with your domain name everywhere.
Replace subl with your favorite editor everywhere such as mvim, mate, or mou.

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

Environment

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

export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"
# required for https://github.com/imathis/octopress/issues/144
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://github.com/imathis/octopress.git kvz.io
cd kvz.io
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 (http://username.github.com/project[gh-pages])

Let octopress know about this

rake setup_github_pages
# Repository url: git@github.com:kvz/kvz.io.git
rake install
rake generate && rake deploy

Note: Different from Github use pages (http://username.github.com/username.github.com[master]).

Setup a domain

echo 'kvz.io' > source/CNAME

Put these DNS records in place

A     record from kvz.io     to 204.232.175.78  (Cannot be a CNAME!)
CNAME record from www.kvz.io to kvz.github.com

Makefile

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

Edit ./Makefile

(Makefile) download

all: tweets dependencies blog

setup:
  rake setup_github_pages\[git@github.com:kvz/kvz.io.git\]

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

tweets:
  rake twitter
  make blog MSG="updated twitter"

comments:
  rake build_comments

dependencies:
  (cd ~/workspace/kvz.io 2>/dev/null || (cd ~/workspace && git clone git@github.com:kvz/kvz.io)) && git pull
  (cd ~/workspace/bash3boilerplate 2>/dev/null || (cd ~/workspace && git clone git@github.com:kvz/bash3boilerplate.git)) && git pull
  (cd ~/workspace/kvzlib 2>/dev/null || (cd ~/workspace && git clone git@github.com:kvz/kvzlib.git)) && git pull
  (cd ~/workspace/transloadit-api2 2>/dev/null || (cd ~/workspace && git clone git@github.com:transloadit/transloadit-api2.git)) && git pull
  (cd ~/workspace/nsfailover 2>/dev/null || (cd ~/workspace && git clone git@github.com:kvz/nsfailover)) && git pull

blog:
  git pull && \
  bundle install && \
  rake integrate && \
  rake build && \
  rake generate && \
  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:

[core]
  repositoryformatversion = 0
  filemode = true
  bare = false
  logallrefupdates = true
  ignorecase = true
[remote "origin"]
  fetch = +refs/heads/*:refs/remotes/origin/*
  url = git@github.com:kvz/kvz.io.git
[remote "octopress"]
  url = git://github.com/imathis/octopress.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"\]
subl source/_posts/$(date +%Y-%m-%d)-blog-with-octopress.markdown

Add an about page

Add & edit like so

rake new_page\[about\]
subl source/about/index.markdown

Add a link to it in the navigation

subl source/_includes/custom/navigation.html

Add an about panel

subl source/_includes/custom/asides/about.html

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

default_asides:
- custom/asides/about.html

More info

Bombs away : )

make blog MSG="Updated blog"

Kevin van Zonneveld

On Development and Internet System Engineering