Hosting with Github Pages

written on May 28, 2013

Jekyll and Github logos

For various reasons, that I might write about later, I decided I needed a place to live on the web1. I wanted a place to write about nerd topics, life, education, parenting, philosophy and other topics that interest me. I also wanted a place to write about some of my dorky half-baked projects. A friend of mine asked me how I am hosting this site, so I thought I would explain my setup.

Use Jekyll

Jekyll is a “a blog-aware, static site generator in Ruby2 that allows you to define simple templates and content in markdown.

It is easy to install and get up and running.

~ $ gem install jekyll ~ $ jekyll new my-site ~ $ cd my-site ~/my-site $ jekyll serve # => Open http://localhost:4000

They have fantastic documentation that explains the directory structure, built in functions and configuration.

Use Github

The site is freely stored and freely hosted at Github. Using Github Pages you can host one of your repositories as a website. Each time you push your code to the repository, the site is statically generated. Their documentation will get you up and running quickly. I followed the instructions that explain how to use Jekyll to host your Github Pages site.

The basic steps are:

  1. Create a repository named <your-github-username>
  2. Place your Jekyll-created directory structure in this repository. (Ignoring the contents of the _site/ directory)
  3. Your newly created site will be available at http://<your-github-username> (after you commit and push your code)

Custom Domain

If you are hosting from a custom domain name3, you will need to configure your DNS records and add a CNAME file to your repository.

  1. You should have an A record pointing to in your DNS configuration at your Domain registrar (or dns provider).
  2. Add a file named CNAME to the top level of your repository, with a single line containing the name of your custom domain. You can view my CNAME file.

A few more things…

I am using the excellent Zepto.js, “minimalist JavaScript library for modern browsers.” It is a small library written by Thomas Fuchs. The same person who created one of the first-generation javascript libraries — It allows for simple animations that leverage CSS3’s animation constructs.

I generate RSS feeds based on the templates provided by Snap Tortoise.

I’ve use the beautiful Proxima Nova font from TypeKit.

If you get stuck you can view this site in my public github repository.

  1. I started out thinking I would host it on SquareSpace, but the tinker-er, in me wanted more control over every silly detail.

  2. I first explored Jekyll two years ago while building an offline magazine viewer. A company had contacted a friend and I about replacing their flash-based DVD magazine archive with HTML. We wrote a boat-load of HTML and javascript running inside of Mozilla’s, now defunct, Chromeless project. It was a fun project. Maybe someday I’ll post the source code.

  3. I’d highly recommend using Hover to register your domain name. They make it very convenient to register and configure a domain.