For this article, I am assuming you already have Jekyll installed, with a project set up on your local machine to generate your static site's HTML files under your build directory of choice.

As a prerequisite to hosting that site on Github Pages, you need to create a Github repository, which nowadays is used for more than code. This is useful anyway since it helps you track the revisions of your code and avoid loosing your work. It’s conventional best practice for developers. Anyone building web stuff with the goal of being able to update his code, track his changes, reuse it, or re-deploy anywhere when needed, should adhere to this practice. You can start here if you are new to creating a repository and pushing code to it.

Let’s say we are working with an example repository, “examplesite”.

Enable the Github Pages service for your project

When you use a Github repository for code, you generally have the main version in what is called the master branch. You may create a new branch later when you need to experiment with some big modifications or a special functionality without impacting the current version.

This separation into branches is used by the Github Pages hosting service. To “hook" your project with the hosting service, you have to create a special branch called "gh-pages", and push only the site’s content, i.e. the HTML code, in that branch. Once you do that, the Github Pages service detects the new content and publishes it to their web server.

Now, with a static site generator such as Jekyll, the trick is making sure the generated static HTML is pushed to the gh-pages branch whenever you are ready to publish an update of your site.

Let's walkthrough the default workflow for this

When you are ready to deploy your site, you would run the build as usual, which generates the static HTML, in a subdirectory called "_site" (by default in Jekyll).

jekyll build

Then, we push the set of updates to the master branch of the repository:

git commit -a -m “New update to the site code and content"
git push origin master

Now, we'll create the gh-pages branch (the first time) and switch to it, since by default we are using the master branch:

git checkout -b gh-pages

We need to put the content of the "_site" subdirectory somewhere temporarily, remove all files from the old Git working tree, then copy the files back to the new working tree, and finally commit the changes. Something like:

cp -Rp _site ../temp/
git rm -rf .
mv ../temp/_site/* .
git add *
git commit -m "Starting to provide content for our Jekyll site"

Last needed step: Push the changes to the gh-pages branch.

git push origin gh-pages

That works! You would be able to see the site by going to your http://USERNAME.github.io/examplesite.

Okay, but what about an easier workflow?

In fact, my pain point was in the need to switch back and forth between the 2 branches, depending on whether I wanted to update the code or the content. It seems like too much is required in that workflow. So I looked for an easier way of doing which does not involve those extra steps. I found one very simple solution, and which did not require any additional tool. Credits to Coby Chapple for this.

Everything is handled from the master branch, including the site build directory ("_site" in this case). The idea is to treat that directory as a subtree.

When ready to deploy the site's content update, we use the special "git subtree push” command to push the subtree to the gh-pages branch.

$ git subtree push --prefix _site origin gh-pages
git push using:  origin gh-pages
Counting objects: 40, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (40/40), done.
Writing objects: 100% (40/40), 909.67 KiB | 0 bytes/s, done.
Total 40 (delta 0), reused 0 (delta 0)
To git@github.com:kamon/examplesite.git
 * [new branch]      4f058ead5c6d0c35975d9529cacebec17e9f1c5e -> gh-pages

That's it!

I am still looking for interesting ways to deploy webapps to GitHub Pages and other agile hosting services, and I will definitely report on what I find useful as I go.