Starting a new blog with jekyll and github

I’m renewing my efforts to generate and publish more code. Here are the steps I took to build a blog with jekyll and free hosting at github. I was brand new to both, so I had to start at the beginning. Here is some more info if you’re unfamiliar with Github Pages and Jekyll.

Github

Create an account at https://github.com/.

On your github dashboard, create a new repository called USERNAME.github.com

Use the following steps to generate an ssh key for pushing to github: http://help.github.com/mac-set-up-git/.

Locally, I created a new folder to host my site:

mkdir USERNAME.github.com
cd USERNAME.github.com

git init
touch README
git add README
git commit -m "Initial commit"

To publish to the github repo, setup the remote and push:

git remote add origin [email protected]:USERNAME/USERNAME.github.com.git
git push origin master

After a few minutes, your code will be live at http://USERNAME.github.com/.

By default, you’ll get a notification (and email) once the page is built. I found this a little excessive and chose to disable emails for “Successful Page Builds” at https://github.com/settings/notifications.

If you’re interested in using your own domain name, create a file called CNAME in the root of your repo with your desired name:

chrislunsford.com

Once that’s done, add an A record at your registrar/DNS provider to point to 204.232.175.78.

Jekyll

Github Pages supports jekyll out of the box.

Installation

You’ll probably want to install jekyll locally for testing. In my case, I was missing a few dependencies. Here’s the meandering path I took on OS X 10.7.3 (updated a few times from lessons learned):

bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)
rvm install 1.9.3
rvm use 1.9.3 --default
sudo gem install jekyll

Configuration

Once it’s installed, you’ll need to build out the file structure. There are a few methods available:

I ended up building it out myself, it’s pretty straightforward:

_config.yml    //jekyll configuration
_drafts/       //draft posts (not required)
_layouts/      //layout templates
  default.html //default template
_posts/        //.md files
_site/         //jekyll will put generated html here
css/           //css files (not required)
index.html

Before the commit and push, create a .gitignore file:

_drafts/  //prevent jekyll from parsing your draft posts
_site/    //these are the generated html files, github-jekyll will build this on its own
DS_Store* //on a mac

Generate Content

Once the structure is setup, markdown files can be dropped into the posts/ directory. Each post should have a YML front-matter section. Full specs for this section are on the jekyll site:

---
layout: default
title: Your Post Title
---

Below the front-matter is your content. Reference the markdown basics page for help on formatting.

Run jekyll locally for testing:

jekyll #one-time command to parse files and generate your site
jekyll --server --auto #parse and server files at localhost:4000, automatically re-parse when changes are detected

Once you’re ready to send to github:

git add .
git commit -m "Commit Details"
git push origin master

Syntax Highlighting

Github Pages uses pygments for syntax highlighting. You can install pygments locally for testing:

sudo easy_install Pygments

In your markdown files, enclose your code blocks with the highlight liquid tags. You can find a list of supported languages on their site.

{% highlight javascript %}
//some javascript
var foo = function(x) {
  return x * x;
}
{% endhighlight %}

The template tags will wrap the block in div, pre, and code tags with the appropriate classes. You’ll need to drop a stylesheet with your preferred styles into your css folder. Pygments comes with a few built-in styles available. You can preview these styles, grab some pre-generated css files, or run pygmentize yourself to generate the css.

I’m using monokai with a few modifications for styling on this site:

pygmentize -f html -S monokai -a .highlight > monokai.css

Changelog

Back