Hey! I'm available for hire (and I appreciate tips)  

This is a follow up to Getting Started with ruhoh as your static blog.

If you're using jekyll, octopress, nanoc, or another ruby- or node-based static blog generator, the instructions are almost identical.

All of the instructions here assume that you're in your blog folder, which should be something like username.github.com (where username is your username, duh).

pushd ~/username.github.com

master is gh-pages

In the previous tutorial we set up the source branch as blog. Now we have to set up a branch for the compiled site.

Note: For some strange reason, the GitHub folks decided to have GitHub Pages for Users and Organizations (i.e. hosting a blog the way we're doing here) use the branch master for compiled sites whereas the you would host project documentation on GitHub Pages using the branch gh-pages.

First we'll backup the current master branch (and create the branch blog from it if it doesn't exist)

# get the a timestamp
NOW=`date +%F`

# rename current master to something else
git branch -m master master-bak-$NOW

# checkout blog or create it from the old master
git checkout blog || `git checkout master-bak-$NOW && git checkout -b blog`

That block of commands is designed for both people who were and weren't following along from the previous article, so even if you saw an error, everything is probably fine.

Created an orphan branch

You only need to do this step once (per blog or repository)

Check the status of your current branch (it should be something like clean working directory)

git status

You'll need to git add and git commit any files that you haven't yet.

Then you'll need to create an empty master branch (it must be that name to work with User GitHub Pages)

# create the branch as an orphan
git checkout --orphan master

# delete all the files (I hope you were clean in the status up above)
git rm -rf .

To kick this branch off, we'll just add a file that ignores the compiled/ directory. (if you're using jekyll or octopress you might want to change that name to public, site, or whatever)

# edit the file .gitignore and add the line compiled
echo "compiled" >> .gitignore

# add it to the repository and commit the change
git add .gitignore
git commit -m "ignore the compiled directory"

# copy it back to github (assume it's aliased as the origin)
git push origin -u master

And after all that hubabaloo, it's safe to switch back to the blog branch.

git checkout blog

Update GitHub Pages

Each and every time you add a new blog article (and you've committed and pushed changes) you need to recompile and push the compiled site to gh-pages.

pushd ~/username.github.com
git checkout blog

# run the compiler (ruhoh, octopress, nanoc, etc)
bundle exec ruhoh compile

# must be clean working directory
git status

# if this fails, you need to add and commit files first, then try again
# (or you didn't follow the one-time instructions above)
git checkout master

# this is a case where the trailing / and ./ are not optional
rsync -a compiled/ ./
rm -rf compiled/

# observe and make guesses as to what's going on
git status

# this is a rare case where adding everything at once is appropriate
git add .

# observe and make guesses as to what's going on
git status

git commit -m "updated compiled site"

# observe and make guesses as to what's going on
git status

# copy the branch back to github (which is the origin)
git push origin master

# observe and make guesses as to what's going on
git status

And then go back to your normal blog branch

git checkout blog

Within about 15 minutes you will get an e-mail notifying you that your page has been built and you are can access your blog at username.github.com.

Using your own Domain Name

If you have a domain (for example, I own coolaj86.com) you can set a CNAME record for blog.yourdomain.com to username.github.com and then inform GitHub Pages to use your domain (it will automatically forward requests from the username.github.com).

If you don't know what any of that means, don't do this step.


echo "blog.YOUR-DOMAIN.com" > CNAME

git add CNAME
git commit -m "hosting an empty blog on branch master"
git push origin -u master

git checkout blog

The redirection should begin to work as soon as the DNS records update (usually about 5 minutes, but up to 24 hours) CNAME record for blog.example.com to username.github.com, It will also be visible there.


By AJ ONeal

Was this useful to you? Share it!

Also, you can give me a tip or hire me.