Getting Started with GitHub Pages and Jekyll

03 Nov 2011

GitHub Pages are the perfect way for geeks to create personal or project websites, blogs. GitHub uses Jekyll, a static site generator.

Requirements

Install Jekyll if you want to preview the generated pages locally. Ruby and Gem are the only prerequisites.

gem install -v 0.11.0 jekyll

Optional: install Pygments if you want to test code syntax highlight locally. See the Jekyll Install page for details. It is recommended to use the same Jekyll version as GitHub if you want to push it.

Create the Basic Layout of Your Site

 .
 ├── _layouts
 │   └── default.html
 ├── _posts
 │   └── 2011-11-11-hello-world.markdown
 └── index.markdown

default.html will hold the HTML code that wraps your content, e.g:

<!doctype html>
<html>
	<head>
		<title>Getting Started with GitHub Pages and Jekyll</title>
	</head>
	<body>
		{{ content}}
	</body>
</html>

Fire up your favorite text editor, open _posts/2011-11-11-hello-world.markdown and create your first post in your favorite syntax (mine is Markdown). The post file name must start with a properly formatted date.

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

## Hello world!

Now you can run Jekyll locally:

jekyll --server --auto

Open http://localhost:4000/2011/11/11/hello-world.html and you should see the miracle.

It is useful to have an index.html to list your posts, let’s create index.markdown:

---
title: My First Jekyll Blog
layout: default
---

{% for post in site.posts %}
- [{{ post.title }}]({{ post.url }})
{% endfor %}

Open http://localhost:4000/ and voilà! Now you can add posts, improve the layout and implement some nice design. The following pages are useful for learning more about the tools used:

Jekyll README
Jekyll’s YAML Front Matter is the page metadata between the --- lines.
Jekyll’s Template Data are the variables available in the pages.
Learn to use Liquid, the ‘macro’ language of the pages, and Jekyll’s Liquid extensions.
Learn Markdown or whatever markup syntax avaliable to Jekyll you prefer.

Push it to GitHub

Once you are happy with the newly created site, you can publish it to GitHub. Two options are available:

User/organization pages: myname.github.com repository will be available at http://myname.github.com
Project pages: myproject repository’s gh-pages branch will be available at http://myname.github.com/myproject

More instructions can be found at the GitHub Pages Introduction.

Tips and Tricks

Use `baseurl`

If you are creating project pages, every url has to be prefixed with the project name, e.g:

<a href="/myproject{{ post.url }}">{{ post.title }}</a>

It can even be made configurable:

<a href="{{ site.baseurl }}{{ post.url }}">{{post.title }}</a>

Create _config.yml with the following content:

baseurl: /test

Override this with Jekyll’s --base-url [url] command line switch locally if you like so (e.g. to serve from the root).

Use HTML5 in Pages or Layouts

Maruku understands HTML5 tags. Add this to your _config.yml:

markdown: maruku