Ninja Ferret

The random thoughts of a software developer

Blogging with GitHub Pages

For a while I have been using WordPress to host my blog but recently I have just become a bit disappointed with the way in which I felt I had less control over the page than I would like. I know that there is a lot of flexibility and power within WordPress but it was just something else that I had to learn just to maintain a blog. So, I decided that I would look at GitHub Pages which will give me the ability to have more control and also improve my web design skills.

One of the advantages that I see about using github is that you then have your content in source control rather than just in a database on another server and I always have copies on my computers so there are multiple copies produced to keep the data safe.

Create your github repository

If you don't have an account already then you need to do that first. After that simply create a repository in the format yourusername.github.com which tells github that you want to use this as a github pages repository.

Generate some content

So on my computer I should really clone the git repository:

$ cd github
$ git clone git@github.com:yourusername/yourusername.github.com.git	

Let's add some content - so the first thing is to create an index.html file:

<html>
  <body>
  <p>Hello world!</p>
  </body>
</html>

And now let's push that file to the server:

$ git add index.html
$ git commit -m 'First commit - creating index.html'
$ git push origin master

In my experience the first commit takes a little while for it to appear (~10 mins) so be patient and then go to http://yourusername.github.com. There you go, you have your first page ready to go.

Building your first template

"Is that all there is?" I hear you say, "just uploading static HTML pages to github?"

Well that is not all there is because GitHub generate your site using Jekyll (at the time of writing this is version 0.10.0). Jekyll allows you to use a templating mechanism for standardising the format and layout of your site so let's take a look at our first template.

Create a new folder in your repository called _layouts and create a new file within there called default.html:

<html>
  <head>
    <title>{{page.title}}</title>
  </head>
  <body>
  <h1>{{page.title}}</h1>
  {{page.content}}
  </body>
</html>

We can now go back to our index.html file and modify it to use the template:

---
layout: default
title: Hello World!
---
<Welcome to my new blog, this will be the best blog ever!>

All that is left is to push the changes back up to GitHub for the files to re-compile.

$ git add index.html
$ git add _layouts/default.html
$ git commit -m 'Adding in layout support'
$ git push origin master

What about posts?

Jekyll is a blog aware rendering engine therefore does have post support. All you need to do is to create a new directory called _posts. By default then create a post with the name year-month-day-title.html (e.g. for this very page 2011-02-12-blogging-with-github-pages.html):

---
layout: default
title: My First Blog Post
---
<This is my first blog post, isn't it amazing?>

Push the new page onto the server and wait for it to recompile:

$ git add _posts/2011-02-12-My-First-Blog-Post.html
$ git commit -m 'Adding in layout support'
$ git push origin master

Summary

So there it is, you are now set up to build your blog, there is a lot more to play with but the basics are there. I will be taking this further in a number of posts to come but this is enough to show you how simple the basics are and how easy things are to get going.

Tags:

blog comments powered by Disqus