Hosting your blog on GitHub Pages
Published 2013-2-6This 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.
Otherwise:
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.
Resources
By AJ ONeal
Did I make your day?
Buy me a coffee
(you can learn about the bigger picture I'm working towards on my patreon page )