Use Hugo to Setup Personal Blog

Welcome to my blog!

This is the first post. This blog is constructed using Hugo. Praise the creators of it!

In this blog I am going to introduce the procedure of building this blog.

Introduction

Hugo is a framework written in Go to generate static blog site from various formats of content. It has various shining points:

• It can be easily configured in a TOML configuration file. In my humble opinion, TOML files are easier to work with compared with YAML or JSON.

• It supports Org Mode natively. As an Emacs user, I can simply write my blog posts (like this one) in Org Mode and Hugo will convert it to static HTML files.

The files generated by Hugo are put under a specific directory public/, which can be directly copied to remote server and hosted by any web server, e.g. Nginx.

The official quick start provides very detailed information of setup a blog site. Here I only introduce some confusing parts.

Themes

Hugo supports different themes. It is relatively easy to switch to another theme. I am using Hermit, but please note that this theme cannot be used directly with quick-start. The best way to use it is to copy its sample configuration file themes/hermit/exampleSite/config.toml to the root directory and customize it.

Code Syntax Highlighting

From Hugo 0.28, chroma is used to provide syntax highlighting functionality. You need to add the following lines into config.toml file:

# Enable syntax highlighting for code blocks.
pygmentsCodefences = true
# Use your favorite code theme here!
pygmentsStyle = "pygments"

Voilà! Now you have the magical power. No need to install external programs or generate any CSS file.

Tags

Hugo provides functionality to categorize posts called taxonomies. It can be enabled by adding following snippet to config.toml file:

[taxonomies]
tag = "tags"

Then while editing posts, simply define tags and Hugo will handle it for you. For Org Mode this done by adding option #+TAGS.

Hugo will tag posts with given tags and provide a page to list all tags, under the URL tags/.

See this page for more detail.

Deployment

Deploying to Your Own Server

I am using Nginx to serve generated static files, so I can simply use rsync to deploy blog posts described here.

Deploying to GitHub Pages

GitHub provides free web page for each project, which might be a good idea if you want to save budget.

First you have to create a public repository of format <username>.github.io. Replace the <username> with your GitHub username. The repository should contain all the files under public/ directory (not itself).

If you are using Git to manage the source code of your blog, it is highly recommended to add this repository as a submodule of the original repository:

git submodule add git@github.com:/<username>/<username>.github.io public

Afterwards, every time you want to modify the content, simply run the following command:

hugo
cd public/ && git add . 
git commit -m "add new content" && git push

You will see the updated blog after refresh.

Summary

In conclusion, Hugo implements functionality for a typical blog. It can be configured easily to setup a blog without a single line of code. Also its out-of-box native support for Org Mode, Markdown etc really shines.