Lessons learned with Jekyll and Github Pages

One of my projects at the moment has a requirement to create a semi static site for documentation to be hosted on Github. The fact you can do this in Github is great, but we wanted to make the documentation fit the rest of the application in terms of look and feel. So over the last week I’ve been created a Jekyll site which has a set of layouts and then a bunch of posts for content. In theory it’s a great way of creating these sorts of sites, but I found there were several peculiarities when using Jekyll in combination with Github Pages that weren’t immediately obvious.

So a little about my configuration first of all. I’m running a Mac with Mavericks installed, and I wanted to be able to do local testing of the pages. This involved several steps to get set up:

1. Install Xcode, this is needed to install some of the command line tools we’re going to need later on.

2. Once Xcode is installed then you need to install the command line tools (so that we can then install Ruby). I think this has been made more difficult, so I’m not sure how long these instructions will work, but as of November 2013, you need to open a terminal window and type:

   xcode-select -install

3. Once that process has completed (it will all take a while), we need to install Ruby, so again from the terminal window:

   \curl -L https://get.rvm.io | bash -s stable --ruby

4. Again this may take some time, but once we’re done then we can create out Jekyll site.
5. First we want to make sure we’ve got the appropriate Github project cloned to disk and then switched branches to the “gh-pages” branch. If it’s not been created then you can do this from the Settings page of the project on the Github website.
6. Delete any content in the site, and navigate to the folder in your terminal window
7. Now we’re going to generate an empty site:

   jekyll new my-site-name

8. Once the site is generated, move the content into the root of the Github project folder
9. Now we need to go and modify the _config.yml file. Now this is quite important and I’m very much a noob at this, so these settings are what work for me, YMMV:

   safe: true
   lsi: false
   pygments: true
   baseurl: /my-site-name
   markdown: rdiscount
   permalink: /docs/:title.html
   

10. If you specify the markdown setting, you’ll also need to install the rdiscount Ruby Gem:

    gem install rdiscount

11. You’ll also want to add a “.gitignore” file to the root of the folder and put in it:

    drafts
    _site
    

12. Now you can run the server, with a few extra switches so that it will live generate any changes that you make to the site:

    jekyll serve --watch --baseurl ''

13. The baseurl switch is important because locally you want to run http://localhost:4000/index.html but on Github Pages you will be running http://my-site-name.github.io/my-site-name/index.html, so the default setting is made in _config.yml and you’re overriding when starting your local server.
14. Now you’ll want to create index.html, my suggestion is that you make use of the default.html file located in _layouts to control the look and feel of your site, just put content into the index.html page.
15. And then you can start creating real content in the _posts folder.

Once you sync up to Github changes are not visible immediately they can take up to ten minutes to show, which is why you want the local server.

A few other bits and pieces that I learned after a bit of messing around:

• Changes to the _config.yml file require you to restart the Jekyll server, everything else will be picked up live (if you’ve used the –watch switch)
• I couldn’t work out how to host images, so you’ll need to put those up somewhere else, I use a public readable Amazon S3 bucket.
• There are various chunks of code which Jekyll has for outputting lists of posts, but none of them matched what I needed so in the end I hard coded quite a lot of links. When building links, make sure to use this format:

  <a href="{{ site.baseurl }}/docs/MyPage.html">My Page</a>
  

  The baseurl is coming from the _config.yml file, the “/docs/” part is coming from the permalink, you can set this up however you want, but I found this easier than trying to use the date format links which there Jekyll site seems to recommend. The “MyPage.html” element is the file name of the post document.

• Beware case sensitivity! On my local server it was forgiving of getting file name cases wrong, but Github is not so generous, that wasted several hours of my life!

Overall Github Pages with Jekyll is nice if you’re wanting a semi static, nice looking website, so perfect for documentation and lots of people seem to use if for blogs as well. Personally I found the whole thing a little painful to use, but each to their own!

 

 

Tags: githubjekyll