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

all: tweets dependencies blog

setup:
    bundle exec 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:
    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"\]
$ subl source/_posts/$(date +%Y-%m-%d)-blog-with-octopress.markdown

More

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.yml so it will be included on every page:

default_asides:
- custom/asides/about.html

More info

Bombs away : )

$ make blog MSG="Updated blog"

Thanks