A Tutorial for using Hugo and Github Pages as a Blog Site

Hugo, a Static Site Generator

Hugo is one of the static site generators. Currently it is ranked 4th by StaticGen. Of the top competitors, Hugo is the only one written in a compiled language (Go), which builds the site much faster. So I decided to give it a spin.

Most of them were written in JavaScript. Jekyll was the good old player in this field, which was used in Obama’s campaigns to raise $250M. Healthcare.gov switched to CMS-free style with Jekyll in 2013.

Hexo uses node.js, which started in 2012. Hugo started in 2013. Both are getting quite popular within a short time. Hugo seems to have a nice growing community and fairly good documentations. It may be missing some features but let’s hope it will catch up.

Deployment at Github Pages

I won’t be verbose about the benefits of static pages. Healthcare.gov and my blog here load blazing fast compared to dynamic sites where the server needs to pull data from different sources. The key reason for me is the flexibility of the content/design control. You are not limited by a small set of templates and widgets such as those found at Blogger. You don’t have the limitations at Wordpress.com in case if you want to put ads on your blog.

The ability to deploy the site with github pages is special since it connects with your github account and your repositories. The entire site can be version controlled as well as the generated site as a git submodule. You are basically making git commits in the meantime that you are updating your site.

Themes for Hugo

There are a variety of templates available at Hugo’s official site, covering different purposes from personal blog, documentation, project information, merchant, designer showcases, to many more. I really liked the material docs design, which was intended to be used as a project documentation/information site. I customized the template for a blog site.

Customize the hugo-material-docs Themes

Main changes for the customization are:

• Changed the index page to list most recent posts/articles.
• Added sections to list blog categories and tags.
• Integrate Disqus comments at the bottom of each post.

The customized template is available at my github repo here. The color pellets can be customized. I chose deep orange as the primary color hoping to warm up the cold coding talks.

To use the template,

git clone https://github.com/JesseZhuang/hugo-material-blog.git themes/hugo-material-blog
hugo -t hugo-material-blog

or setup the theme in config.yaml or config.toml.

I did notice some weird bugs while I was customizing the template. Sometimes the template engine report errors if you have commented out lines in the template.

I plan to keep this template updated while writing more articles for the site. You are welcome to comment here or at my github repo for any issues or feature requests.