«
»

Publishing a Blog with GitHub Pages and Jekyll

8.5.09 by Tyler Hunt

GitHub Pages

Many people turn to GitHub for Git repository hosting, but did you know every GitHub account also includes basic web hosting? Not only is it free, but if you know how to push to a Git repository, you know how to deploy to GitHub Pages. It’s as simple as creating a repository called username.github.com.

Getting Started

We’re going to walk through the process of setting up and pushing out your first GitHub Pages page. If you’re already familiar with HTML and Git, you’ll see that there’s nothing really new here. Just bear with me and we’ll get to the good stuff below.

First, we’ll create a directory for our new site.

mkdir envylabs.github.com
cd envylabs.github.com

Then, let’s create an index.html file that looks something like this:

<!DOCTYPE html>
<html>
<head>
<title>Envy Labs</title>
</head>

<body>
<h1>Envy Labs</h1>
</body>
</html>

Initialize the repository and commit our new index file.

git init
git add index.html
git commit -m 'Initial commit.'

Then push to GitHub and cross your fingers.

git remote add origin git@github.com:envylabs/envylabs.github.com.git
git push origin master

Your page should be live at http://username.github.com/ in about 10 minutes.

A static HTML page.

Subsequent changes seem to be picked up almost immediately, and updating your site is as simple as adding and updating files and pushing to GitHub.

Jekyll

Tagaholic

Editing static HTML files works just fine, but it isn’t the most practical way to maintain a site. This is where a tool like Jekyll really shines. It’s is a static site generation tool built by Tom Preston-Werner. It lets you build out your site using HTML, Markdown, or Textile and then runs everything through the Liquid templating engine. It supports layouts and a few other tricks to make it easy to manage a blog.

We’re going to install it locally so we can preview our page before we push it up to GitHub. It’s a good idea to match your local version to the one that GitHub is using. You can find the version of Jekyll they’re using on the GitHub Pages home page.

sudo gem install mojombo-jekyll -s http://gems.github.com -v 0.5.2

Starting with our original version of the site—just a simple index.html file—we can begin to see the power of Jekyll by creating a layout and converting our index file to use it.

Create the file _layouts/default.html.

<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }}</title>
</head>

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

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

Then update index.html.

---
layout: default
title: Envy Labs
---

Welcome!

The “YAML Front Matter” at the top will let Jekyll know that we want this file processed wrapped with the template named default, and will set a variable called page.title that we can use in our templates. The rest of the page will be output in the layout where we have the {{ content }} tag.

To see it in action, run jekyll --pygments from the root of your site (the --pygments option will enable syntax highlighting for code snippets). The generated output is put into the _site subdirectory. Open up _site/index.html in your browser to see what it produced.

A Jekyll Layout

A simple git push is all you need to update the live site. Every time you push to GitHub it will automatically run jekyll --pygments on it before publishing.

Blogging with Jekyll

Paperplanes

Jekyll has some rudimentary support built in for generating blogs. It relies on a special naming scheme where all of your posts go under the _posts subdirectory, and each post is named year-month-day-the-title-of-the-post.format where format is one of html, markdown, or textile depending on your markup language of choice.

For the first post, create the file _posts/2009-08-05-first-post.markdown.

---
layout: default
title: First Post
---

This will be the best blog ever.

Now, let’s update our index to list out the five most recent posts.

---
layout: default
title: Envy Labs
---

{% for post in site.posts limit:5 %}
<h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
{{ post.content }}
<em>Posted on {{ post.date | date_to_long_string }}.</em>
{% endfor %}

See the page on template data for a full listing of the available variables.

A Jekyll Blog

While this simple layout works, you can extend the concepts you’ve learned to flesh out the design and features of your blog. For instance, you might want to create a separate layout for your individual posts, or generate a feed using an XML file with the same YAML front matter and Liquid tags you’ve already seen.

If you’d like comments on your Jekyll blog, check out Disqus. You can add comments to a post using JavaScript with a snippet like this.

<a href="{{ page.url }}#disqus_thread">View Comments</a>
<div id="disqus_thread"></div>
<script type="text/javascript" src="http://disqus.com/forums/[your-site-name]/embed.js"></script>

There are some additional resources further down that you might find useful.

Custom Domains

Tate Johnson

GitHub pages also supports pointing your own domain to your site, but it only works on paid accounts and repositories with contributors who have paid accounts. It’s simple to set up, but may take around a day for the changes to fully propagate.

Start by creating the file CNAME in the root of your site containing the domain name you’d like to have pointed to your GitHub Pages site.

pages.envylabs.com

Then, after you add this file and push to GitHub, you’ll need to modify your DNS settings by adding a CNAME entry for your desired domain that points to your GitHub Pages domain. In our example, we could create pages.envylabs.com and point it to envylabs.github.com.

That’s all there is to it. Wait patiently, and you should be good to go.

Project Pages

Ambition

We’ve seen how to create a site for your GitHub account, but you can also create individual sites for each of your projects at http://username.github.com/project-name. This could be used for a full on sub-site for each of your projects, or just as a place to stash RDocs or other documentation.

GitHub will look for a gh-pages branch on each of your projects, and will use that as /project-name on your GitHub Pages site if one is found. The tricky part here is creating a branch without ancestry. I’ve seen a few different ways to do this, but none are easy and all have caveats.

This is the method that GitHub preaches. You’ll need to make sure you don’t have any uncommitted changes before doing this, so commit or stash first or you’ll lose them.

git symbolic-ref HEAD refs/heads/gh-pages
rm .git/index
git clean -fdx

Then add and commit your site and push to GitHub with git push origin gh-pages. Just as with regular pages, it might take up to 10 minutes for GitHub to pick up on the new site the first time around.

Additional Resources

Teddy Zetterlund

That should be enough to get you started, but here are a few additional resources that you may want to check out.

  • GitHub Pages — The GitHub Pages home page covers the basics here, but also links to some real world examples and covers custom 404 pages.
  • Jekyll Wiki — The Jekyll wiki covers more features and configuration options than we’ve taken a look at there. The usage page gives a good overview of everything, and the sites page has a nice collection of sites with source code, which is a good place to look for more examples and inspiration.
  • Liquid Templating Language — The Liquid site may be useful if the syntax of the Jekyll templates is new to you.

Related posts:

  1. Getting Started with the Rails 3 BugMash
  2. The Envy Labs Blog
  3. Census: Rails Demographics Collection

24 Comments

, , ,

24 Responses to “Publishing a Blog with GitHub Pages and Jekyll”

Comments


  1. Joshua Blount says:
    August 5, 2009 at 2:38 pm

    Nice, I would love to have similar support in Launchpad.net, sounds really useful.

  2. Publishing a Blog with GitHub Pages and Jekyll « Envy Labs « Netcrema - creme de la social news via digg + delicious + stumpleupon + reddit says:
    August 5, 2009 at 4:17 pm

    [...] Publishing a Blog with GitHub Pages and Jekyll « Envy Labsblog.envylabs.com [...]

  3. Valentin Jacquemin says:
    August 8, 2009 at 3:46 pm

    FYI, hyde follows the same principle but is developped in python.
    http://github.com/lakshmivyas/hyde/tree/master

  4. Andre Bernardes says:
    February 25, 2010 at 5:05 pm

    Hiya! As an update: Since Jan 9th 2010, you can install jekyll using:
    sudo gem install jekyll

    It will install jekyll 0.5.7, same version used by github pages

    ;)

  5. Les Freeman says:
    March 5, 2010 at 5:30 pm

    How do you get Jekyll to process xml files? I’m trying to create a feed and not having any luck.

    Thanks!

  6. Russia says:
    March 30, 2010 at 11:16 am

    Hey very nice blog!! Man .. I will bookmark your blog and take the feeds also…

  7. Sindhu S says:
    May 12, 2010 at 4:38 pm

    Hi! In the command to install mojombo-jekyll the command line option should be captial V not small letter v as its mentioned in the blog post, please correct it.


Leave a Reply

* Required Fields

Additional comments powered by BackType