Blogging With Hugo

This blog is hosted for free on Github Pages. But it is built using another service called Hugo. If you look at the site footer, you should find a link to their project website.

In their website, they say they are the world’s fastest framework for building websites. It is a static site generator written in Go with extremely fast build times (~1 ms per page). Content is written in markdown with front matter. Hugo then takes the source directory with content and templates and renders them into a full html website.

Below is a quick start introduction to Hugo to get your own blog up and running in less than 30 minutes.

The first thing that you need to do is install Hugo on your machine.

If you are on a Linux or Mac, you can use Brew to install Hugo. For more options, see the official install docs here. It’s also recommended to have Git installed as well because it will make content management so much easier just like software version control.

To create a new site, simple run the command below:

$ hugo new site mysite

This will create a new Hugo site in a folder named mysite. Navigate into the directory, and initialise a git repository inside it.

$ cd mysite
$ git init

Now, you can add a theme to your site. I chose the Kiera theme for my blog. You can choose any theme that suits your purpose from their collection of hundreds of themes here. It’s recommended to download the theme into your site by using git submodule like below:

$ git submodule add https://github.com/funkydan2/hugo-kiera.git themes/hugo-kiera

A new .gitmodules file will be created containing the local path and remote URL of the submodule.

Then, add the theme to the site configuration:

$ echo 'theme = "hugo-kiera"' >> config.toml

Now you can start creating content by using the hugo new command from the site root like so:

$ hugo new posts/my-first-post.md

This will create a post by the name my-first-post in a posts sub-directory inside the content directory of the site.

Open the file in a text editor of your choice and start writing. Each new content file starts with some extra information about the post called front matter like this:

+++
title = "My First Post"
date: 2019-03-26T08:47:11+01:00
draft: true
tags = []
categories = []
+++

You can start writing directly the contents below the front matter in markdown format as usual.

Once written, set the value of drafts in your file’s front matter to false, and launch a development server using the command

$ hugo server

By default, this command will not deploy the files which have drafts as true. (Read More)

To deploy draft files, use the command:

$ hugo server -D

Once, you are satisfied with your changes, stop the server, and build your site by simply using the command:

$ hugo

To build the drafts too, use the command:

$ hugo -D

Output will be in the /public/ directory by default. You can change it by setting publishDir to a directory name of your choice in the config file. You may then deploy your site by copying the public/ directory to your production web server.

Now, to deploy this site using Github pages, simply create a repository of the name username.github.io where username is your Github account ID. It’s necessary to create the repo of that name because Github gives you a free website using your uniquie ID on the github.io domain.

Clone the repository on your computer and add the contents of your site’s public directory into this new repo. Finally, commit and push. Your site should be live in a few minutes on your unique github.io domain.

Before committing and pushing your mysite repo to Github, first delete your public directory and add your username.github.io repo as a submodule with the directory name public like so:

$ rm -r public/
git submodule add <Remote location of your username.github.io repo> public/

It may happen sometimes, that a git directory for ‘public’ is found locally with the above remote. If you want to reuse this local git directory instead of cloning again from the remote, use the ‘–force’ option.

Now, every time you add new content to the site and build it, your public directory will be updated. You can navigate inside the public directory and update your username.github.io remote repository.

Once updated, navigate back to the mysite root, and update its remote repository without pushing the contents of your theme or public directory. Instead, only a refernce to specific commits are added. (See example)

That’s pretty much it. You should have a workflow set up to publish and maintain a static site or blog powered by Hugo. You can do some customizations based on your need. For example, I made a custom static home page for my blog instead of using the default list page view of the hugo site by adding a new post called _index.md, and display a list page for posts by adding a posts.md file in the archetypes directory.

Check out the official docs for more details.