← home← blog

Hosting your Blog or Portfolio on GitHub

21 Nov 2013

Everyone and their mother is now telling you to "stick your site on GitHub", but if you don't know what a GitHub is or the idea of forking, pushing and committing freaks the hell out of you, then I hope this short guide will at least help you overcome those barriers and come to realise that it's a dream workflow to have your site hosted on GitHub and all the benefits that come packaged with it.

Why the sudden increase in popularity?

Well, as GitHub's own popularity has grown and is finding itself more deeply engrained into developer's workflows, more and more projects are going up on GitHub and therefore more project/demo pages are being hosted on GitHub. Naturally, as more of your stuff is on GitHub and your workflow is more finely tuned, the next step is hosting your blog or portfolio on GitHub using the same workflow.


  • It's free
  • A lot of people use it, so there's lots of help
  • You can optionally use Markdown, which is ace
  • You can edit and re-upload your files directly on the site (GitHub.com)
  • It's free

Enough talk, let's get going…

Create your repository

If you're not already signed up to GitHub, head over to GitHub.com and sign up. Otherwise, head over and create a repository. Make the name the following: "[yourGitHubUsername].github.com", so mine would be "benhowdle89.github.com". Mark it as "Public" (it is by default). Then just hit "Create Repository".

Editing and uploading files

Next step is to put files up onto GitHub from your local machine. If you want to/are comfortable with using Git on the command line, then by all means, go for it. But if you want to use a GUI, then GitHub provide an excellent Mac App for you to download.

Once downloaded, you should be able to sign in and see a similar pane to the one below…

You should then see all of your GitHub repositories on the right-hand side…

Once you hit the "Clone to Computer" button, it should ask you where you want to save the folder on your machine and then take you to a similar view to the one below…

Any file that you change in the saved folder is going to show up here, ready to be uploaded to GitHub. Pressing "Commit & Sync" should do just that, upload to GitHub (and therefore, put the changes live on your portfolio).

To make it easy for you, I created a really simple, one page, HTML portfolio on GitHub, which can be Viewed or Downloaded. Feel free to copy all the downloaded files into your local folder and upload them to GitHub as a quick start exercise.

You should now be able to visit [yourGitHubUsername].github.com and see your shiny new portfolio! You can see mine at http://benhowdle89.github.com, it will redirect to http://benhowdle.im but I'll explain why and how you can do that in a few moments…

You mentioned a blog?

I created a second repository for you to View and Download. This blog is powered by Jekyll, a Ruby backed, static site generator, which is really great for smaller sites and blogs. However, using it is a bit beyond the scope of this tutorial, but the docs on the site are brilliant and I wrote a Jekyll In 15 Minutes post which gets you going with it really quickly!

Custom domains

You'll notice that the blog you're reading is located at http://benhowdle.im, which is hosted on GitHub. There are two things you have to do to be able to do this. Firstly, you need to create a file in your local site folder called "CNAME" (very important it's uppercase, and note the lack of file extension). Place this in the root of your folder and put your custom domain name in the file, ie. like mine, then upload as you normally would. Secondly, now this might vary depending on who you registered your domain name with, but you need to create an A record pointing to GitHub's IP address (, like so:

Once that's done and DNS propagation is complete (can take years…not years, but it feels like years), you should be able to visit your domain and see your GitHub hosted portfolio!

Did I miss anything?

I hope this guide will help you out with hosting your portfolio on GitHub. Remember, you're just creating a set of HTML and CSS files, like you're used to and uploading them to the internet. For free. You just have to get a bit comfortable with some of the lingo used, ie. repositories and committing, etc…

If I have missed a step somewhere along the way or you get stuck, please do drop a comment below or tweet me.

I'm available for hire

Hire me