micmath blog

Publish A Developer Blog on GitHub

Posted Monday, 05 April 2010 by Michael Mathews in Code.

If you use GitHub you may not realise you already have access to website hosting, accessed via your user name. You can publish content there, once it is set up, but I want to go a step further and set up a blog. This post documents the steps I followed to do that.

Set up you github user page

First you need a user account on GitHub. If you go to a URL like http://yourUserName.github.com you will see the instructions you need to follow to set up your user page. I'll detail how I created mine:

Create a pages repo on github. Mine will be at http://micmath.github.com/

$ mkdir micmath.github.com
$ cd micmath.github.com
$ git init
$ echo "My GitHub Page" > index.html
$ git add index.html
$ git commit -a -m 'Initial commit.'
$ git remote add origin git@github.com:micmath/micmath.github.com.git
$ git push origin master

It can take about 10 minutes for the initial setup. That will give me time to install a few other things on my local machine...

Install the template system

GitHub supports Tom Preston's Jekyll engine and Pygment natively, so it makes sense to use those for a blog hosted on GitHub. I'm using gem and port to get the software on my Mac, you may need to use a different installation process supported by your own OS.

Install Jekyll for templates and site generation.

$ gem install jekyll

Install Pygments, for source code highlighting.

$ sudo port install python25 py25-pygments

Set up the site file structure.

$ mkdir _posts
$ mkdir _site
$ mkdir _layouts
$ touch _config.yml
$ mkdir css

Add the Pygment stylesheet

Pygment can generate it's own stylesheet, to be used for source code highlighting, using the command shown below. Jekyll uses the CSS selector ".highlight code", so add that in and create the file, like so:

$ pygmentize -S default -f html -a ".highlight code" > css/syntax.css

Configure Jekyll

You can configure Jekyll to your liking. For example I have my own Apache server running locally so I don't need Jekyll to run one.

$ cat _config.yml
auto: false
server: false
pygments: true

Create the default layout and css

$ touch _layout/default.html
$ touch css/default.css

In _layout/default.html, add some template code. Jekyll uses the Liquid template syntax, plus a few Jekyll-specific extensions.

$ cat _layout/default.html
<!DOCTYPE html>
<html>
    <head>
        <title>{{ page.title }}</title>
        <meta http-equiv="Content-Type"
              content="text/html;charset=utf-8">
        <link rel="stylesheet" type="text/css" media="screen"
              href="/css/default.css" />
        <link rel="stylesheet" type="text/css" media="screen"
              href="/css/syntax.css" />
    </head>

    <body>
        <h1>{{ page.title }}</h1>

        {{ content }}
    </body>
</html>

Create some content

Finally, all the infrastructure is now in place and we can start blogging! To create the content for a blog post, simply add a new markdown file to your _posts folder. The name of the file should be formatted like yyyy-mm-dd-your-title.markdown.

$ cat _posts/2010-04-05-hello-world.markdown
---
layout: default
title: Hello World
---

This is an example blog post.


This is a just a _test_. Here's some code, which will get syntax highlighting from Pygment:

{% highlight js %}
    function Foo(x, y) {
        this.x = x;
    }
{% endhighlight %}

Generate the HTML output

If you want to preview your formatted blog post you can run jekyll locally. This step is technically unnecessary, since GitHub will automatically run this same command for you on the server whenever you push new content. However it's handy if you want to proofread and tweak anything before publishing.

$ jekyll
Configuration from ./_config.yml
Building site: . -> ./_site
Successfully generated site: . -> ./_site

There is no need to publish the HTML generated in your own workarea, GitHub will automatically regenerate it whenever you commit anyway. So, if you haven't already done so, add the _site folder to your .gitignore file.

$ cat .gitignore 
.DS_Store
_site

Publish the content

Publishing is easy, just commit and push and new files. If you haven't already done so, add all the new folders and files to git. Finally commit and push:

$ git commit -a -m 'Added source code example.'
$ git push

permalink | Tags: git.