Hosting Pages on GitHub

I’ve been talking back and forth with @jasongreen on Twitter recently about Jekyll and hosting sites through GitHub as well as how to generate those files. Thought this would be a good opportunity to throw up a tutorial on getting started which we can build on with other aspects of the workflow (like pulling into your Reclaim space, generating Jekyll files locally, etc).

For this tutorial I’m going to walk through the process of hosting a barebones demo site with the Pixyll Jekyll theme. This theme is available on Github so it’s quite easy to fork it to your space, make some modifications, and be up and running.


First a point of clarification about GitHub Pages. The URL the GitHub creates is based on whether it is a “Project Page” or a User/Organization page. User/Organization pages follow the format but the repo has to be called with that same format In a user page all work is done directly in the Master branch. The alternative are “Project Pages” which use a special branch for hosting the website information (so that ostensibly an actual software project could be hosted at the Master branch). GitHub has a page about User/Organization/Project Pages


For the purposes of this tutorial I’ll setup a Project Page. First I need to fork the repository to my own account to make any modifications to it.


Now that I have a copy of the project I’ll open up GitHub for Mac to clone a copy to my laptop. I grab the repository from my account and have it create a folder on the desktop.


Within GitHub for Mac you can change the branch you’re working in at the top. I switched to gh-pages since that’s where project pages are hosted. The next thing I need to do is open the config.yml file to add my settings. YML stands for “Yet Another Markup Language” and has become something of a standard in various places but basically it’s just a syntax for adding settings to your site. You’ll see here we’re I’ve updated quite a few settings. Of not is the URL pattern for url and baseurl which must match up with where it’s going to be hosted.


Mostly just changed the title, added some social icons. Now that the text is edited I save and move back to GitHub for Mac and it detects all of those changes. I can add a commit message and then sync it with the repository on GitHub.


Indeed if I go to the Settings directory I’ll see confirmation that the site is live at


And if I shoot my browser that way my new site is live. This is the first very basic intro to Jekyll, we’ll get into some more advanced scenarios in other topics. If you’re playing with this stuff I’d love you to consider writing some of it out for the benefit of the community.


I’m up and running, but I’m now confused about editing the site. With the username.github,io scenario one can add a markdown (,md) file to the Master branch and a corresponding .html file is created automatically. This doesn’t seem to happen when you are building in the gh-pages branch of a project repository, or am I missing something?

I don’t think that’s true actually. If I understand Jekyll correctly (which admittedly I don’t) markdown files have to live in the _posts folder in order to be rendered as static html (

The other confusion I think we were both having is that apparently Github’s Jekyll rendering does not place the generated _site folder in the repo, it simply makes the static contents that normally would be there available on the web. So no .html files get created automatically unless you run Jekyll locally and do a build (which could then be pushed to the GitHub repo).

That explains a good bit of my frustration since:

  • I am trying to use this for a static site, rather than a blog
  • I’m doing all the experimenting in github because I can’t get a local instance of Jekyll to install/run
  • I’d like to pull the gh-pages branch into my root public_html directory so I can edit markdown files and have them automatically added to my static site.

Apparently github project pages does none of these things easily. Maybe I need to add Jekyll to the managed software hosting wish list. :slight_smile: