Hosting Project Documentation on GitHub PagesPublished 2013-2-6
don't follow this guide right now, it needs cleanup
I'm going to use ruhoh as an example, but if you're already using jekyll, octopress, or another ruby static blog, you'll probably know what you need to change.
Rename master to old-master
git branch -m master old-master
Created a gh-pages branch
You only need to do this step once (per blog or repository)
If you were following along with my previous tutorial then you'll need to get into your blog folder which should be named something like username.github.com.
Check the status of your current branch (it should be clean)
You'll need to
git add and
git commit any files that you haven't yet.
Note which branch your on (it'll be the one with a * by it, probably be blog or master)
Then you'll need to create an empty gh-pages branch (it's a special branch name only used by github)
# create the branch as an orphan git checkout --orphan gh-pages # delete all the files (I hope you were clean in the status up above) git rm -rf .
For starters, we'll just add a file that ignores the
(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 gh-pages
And after all that hubabaloo, it's safe to switch back to your normal branch. For example, if it was blog you would do this:
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 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 gh-pages # this is a case where the trailing / and ./ are not optional rsync -a compiled/ ./ rm -rf compiled/ # this is a rare case where adding everything at once is appropriate git status git add . git status git commit -m "updated compiled site" git status git push origin gh-pages git branch master git push origin -u master git checkout blog
Hosting your blog on github pages
This set of commands is completely optional, but since we're already on github and all I thought it would be appropriate to give the hosting instructions.
rm -rf compiled/ bundle exec ruhoh compile git checkout gh-pages rsync -a compiled/* ./ rm -rf compiled/ echo "blog.example.com" > CNAME git add . git commit -m "hosting an empty blog on gh-pages" git push origin -u gh-pages 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
As soon as you set the
CNAME record for
It will also be visible there.
By AJ ONeal
Did I make your day?
Buy me a coffee