As a first blog post I thought I’d start by walking through how I made this site and blog using the wonderful GitHub pages, Cloud9 and Jekyll, and how you can do the same. All you need is a browser - no local development environment necessary.

Github

First up, you’re going to need a GitHub account. Each account gets one GitHub site, which is all stored and hosted by GitHub. Once you’re signed up you need to create a new repository with the following naming convention: username.github.io, where username is your github username. The naming convention tells GitHub that you want to use the repository as a website. This repository will eventually contain all the code needed for your site, and any changes within the repository will immediately be visible on the site.

Cloud9

At this point many guides will lead you away down the local ruby installation road, with all of its OS dependent intricacies and version headaches. If the operational details bore you, check out Cloud9. It gives you access to a fully featured development environment in your browser, all hooked up to a virtual machine in the background with everything you need pre-installed. It’s almost too easy.

Sign in to Cloud9, then link to your GitHub account; doing this at the start is the least painful way of getting the two talking to each other. Once they’re linked, a list of your GitHub repositories should appear on your Cloud9 dashboard. Select the one you created earlier and click the ‘CLONE TO EDIT’ button. We just want a standard machine, so choose a ‘Custom’ project type. You should now be presented with the Cloud9 IDE.

Jekyll Install

Now we need to do a few operational steps to get Jekyll installed. First, execute gem install bundler in the terminal to get the bundler package manager. Then execute gem install jekyll. Once Jekyll is installed, delete the README file in the root directory and execute jekyll new . to create the jekyll scaffold. Open a new terminal and execute jekyll serve --host $IP --port $PORT (the extra arguments are needed for cloud9) to run our jekyll server. You should be able to open the link in the pop up and see a basic site.

Creating the Blog

The site looks great, but if you want to use it as a landing page and have your blog separate we have to do a few fiddly configuration steps.

First create a folder named blog in the root directory. Inside, create a file index.html. We’re going to cut some of the content of our home page, which is given in our index.html file in our root subdirectory, in to this file, shown below:

<ul class="post-list">  
  {% for post in site.posts %}
    <li>
      <span class="post-meta">{{ post.date | date: "%b %-d, %Y" }}</span>
      <h2>
        <a class="post-link" href="{{ post.url | prepend: site.baseurl }}">{{ post.title }}</a>
      </h2>
    </li>
  {% endfor %}
</ul>

<p class="rss-subscribe">subscribe <a href="{{ "/feed.xml" | prepend: site.baseurl }}">via RSS</a></p>


Finally, we need to add a line to our _config.yml file to tell it where our posts are.

permalink: /blog/:categories/:year/:month/:day/:title.html


If we head over to our served up page the posts on the home page will have gone. Postfix the url with \blog and there are the posts.

Host

To publish the site all you need to do is push your changes back up to GitHub.

git add .
git commit -m "jekyll installed, new site created, blog subdirectory set up"
git push origin master


Navigate to username.github.io to see your shiny new site out in the big wide web.

Personalise

This is the minimum you need to get your blog up and running. At the moment people can’t even navigate to your blog from your home page, so you’re going to want to add a link somewhere so that people can find it. If this is the first time you’ve used Jekyll your next best step is to learn how includes and layouts work; check out the Jekyll docs for details. You might also want to add Disqus comments and twitter sharing buttons to your site: I’ll go through this in a later post.


Thanks to Josh Branchaud for his post on setting up a blog subdirectory.