Azhar Khan

Jekyll + Hydeout + Github Pages

—
Jekyll

I recently migrated my old website from Wordpress to Github pages using Jekyll and Hydeout. Over time, I grew to really dislike how heavy-weight Wordpress is. The WYSIWYG editors make it really hard to work out what HTML is being generated and have an inclination to bloat the code that’s produced. I found the Wordpress plugin system so confusing that i wont to be afraid to try and do to customize the layout of anything.

The process of backing up Wordpress is a huge pain. I was annoyed constantly installing security updates. I hated having to keep an opaque database in order to keep all of my content. And whenever I went in to edit my website, I was always afraid that I would fat-finger change something and have no idea what happened.

So when I learned about Jekyll, it seemed like a great alternative. I like the idea that my entire blog is a set of static files. Besides its simplicity, it makes backups so much easier and avoids most common security concerns caused by running dynamic websites. I could write my posts in Markdown, which is quite handy. Also, Jekyll allows for code examples to be very nicely embedded in the website. Finally, Jekyll is very lightweight and allows for very minimal websites without any bloat.

The fact that GitHub provides free hosting for Jekyll blogs is just icing on the cake. It will save me a few extra dollars each year in hosting. GitHub provides automatic version control of my blog. I can use GitHub’s web editor to write blog posts online. And I can still connect it to my custom domain.

Getting Started #

I came across this really cool git repo called Hydeout which was super easy to setup. Hydeout is a theme built on top of poole. Hydeout updates the original Hyde theme of poole for Jekyll 3.x and adds new functionality.

fongandrew.github.io is a working demo of the Hydeout website that looks like this

The demo Hydeout website

To get started with my blog, all I had to do was create a new Git repo with the name XOR97.github.io, download the Hydeout repository, and push it to my git repo. A few minutes later the website azkh93.github.io was ready! I only had a few posts on my previous website so I just copied them over manually. But there is a package for migrating blogs to Jekyll.

Blog Layout #

The initial state of the Hydeout repository is:

$ ls -1
404.html
Gemfile
CNAME
LICENSE.md
README.md
_config.yml
_includes
_layouts
_posts
_sass
_screenshots
assests/css
category
about.md
favicon.ico
favicon.png
atom.xml
index.html
search.html
tags.html

You can view the folder structure on GitHub. When you run Jekyll, it creates a folder called _site with the static website inside of it. Every file or folder in the repo will get copied into the _site folder unless it begins with an underscore. Markdown files will get automatically converted to HTML and Hydeout uses the Liquid templating system to allow for somewhat dynamic content on the website.

The folder _posts contains all of the blog posts in markdown format. Some example posts that come with Hydeout are:

$ ls -1 _posts/
2013-12-31-whats-jekyll.md
2014-01-01-example-content.md
2014-01-02-introducing-hyde.md

index.html contains the front page of the blog and about.md is a static post in markdown format. If you want to have more static files, you can just add them to the repo and Hydeout will copy them to the _site folder when rendering the website.

_config.yml contains general configuration stuff for the website:

## Setup
title:            Hydeout
tagline:          'The Jekyll theme'
description:      'The <a href="http://hyde.getpoole.com" target="_blank">Hyde</a> theme for <a href="http://jekyllrb.com" target="_blank">Jekyll</a>, refreshed.'
url:              https://fongandrew.github.io
...

Finally, the folders _layouts and _includes contain boiler-plate HTML for building the website.

$ ls -1 _layouts/
default.html
page.html
category.html
index.html
post.html
search.html
tags.html

$ ls -1 _includes/
category-links.html     custom-head.html        favicons.html           page-links.html         post-tags.html          sidebar-nav-links.html
comments.html           custom-icon-links.html  font-includes.html      pagination-newer.html   related_posts.html      sidebar.html
copyright.html          custom-nav-links.html   google-analytics.html   pagination-older.html   search-form.html        svg
custom-foot.html        disqus.html             head.html               post-meta.html          sidebar-icon-links.html tags-list.html

Disqus Comments #

Disqus integration is ready out of the box. Just add the following to your config file:

  disqus:
    shortname: my-disqus-shortname

If you don’t want Disqus or want to use something else, override comments.html.

Google Analytics #

For Google Analytics support, define a google_analytics variable with your tracking ID in your config file.

Getting a Custom URL #

Once I got my blog up to speed on GitHub with the URL XOR97.github.io, it was easy to link my personal domain to it. I use GoDaddy to host my domain, so I followed the instructions here.

I hope this blog post will help you get up to speed quickly with GitHub Pages, Jekyll, and Hydeout. If you have any questions about my implementation, you can view my entire website on GitHub or leave a question below.

Here are some links which helped me along the way: