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.io 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

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 (https://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 (https://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

all: tweets dependencies blog

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

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

tweets:
	bundle exec 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/dotfiles 2>/dev/null || (cd ~/workspace && git clone git@github.com:kvz/dotfiles.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
	(cd ~/workspace/logstreamer 2>/dev/null || (cd ~/workspace && git clone git@github.com:kvz/logstreamer)) && git pull

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

blog:
	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:

[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"\]
$ $EDITOR source/_posts/$(date +%Y-%m-%d)-blog-with-octopress.md

Add an About Page

Add & edit like so

$ rake new_page\[about\]
$ $EDITOR source/about/index.md

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:

default_asides:
  - custom/asides/about.html

More info

Bombs Away :)

$ make blog MSG="Updated blog"