Blogging with Hugo

Jan 13, 2021 hugo blog linux
Share on:

Introduction

Blogging is a really good way to make notes on the things you have learned over the years. Previously I used Wordpress to capture my notes but I found it quite cumbersome.

More recently I became aware of Hugo and decided to give it a try (spoilers this site is the result). Hugo is a really amazing piece of software that enables you to generate a static site. A static site is perfect for a blog, and quickly getting up and running with a local site can be done in a matter of minutes.

Hugo Installation

Hugo is a Go application that supports a wide range of operating systems. This post is based on a Linux host installation.

Two versions exist

  • hugo_${version}_Linux-64bit.deb - does not include support for scss
  • hugo_extended_${version}_Linux-64bit.deb - does include support for scss

Select the version required. NOTE: themes typically require scss support

  1. Set the Version based on the available Hugo packages
1version="0.109.0"
  1. Install the latest version of Hugo on Linux distribution

Standard

1wget https://github.com/gohugoio/hugo/releases/download/v${version}/hugo_${version}_linux-amd64.deb

or

Extended

1wget https://github.com/gohugoio/hugo/releases/download/v${version}/hugo_extended_${version}_linux-amd64.deb
  1. Install the package
1sudo dpkg -i hugo_${version}_linux-amd64.deb

or

1sudo dpkg -i hugo_extended_${version}_linux-amd64.deb
  1. Validate the Hugo version
1hugo version

Generating a site

Hugo supports site generation. A site contains the blog posts and themes that are displayed when accessed.

  1. Create a new site with Hugo, for example roselabs-blog
1hugo new site roselabs-blog
  1. The following directory structure is now available
 1.
 2└── roselabs-blog
 3    ├── archetypes
 4    ├── config.toml
 5    ├── content
 6    ├── data
 7    ├── layouts
 8    ├── resources
 9    ├── static
10    └── themes
  1. Change the current directory to roselabs-blog
1cd roselabs-blog
  1. Generate a blog post

Making a blog post is simple with Hugo:

1hugo new posts/roselabs-first-post.md
  1. A generated blog post will look similar to the following:
1---
2title: "Roselabs First Post"
3date: 2021-03-15T14:55:04Z
4draft: true
5---

NOTE:

  • title: is taken from the hugo command
  • date: is set to the time the post was generated
  • draft: true means is will only show in development mode. A setting of false is required for production

Add a theme

Hugo has many themes available. Themes provide a way to enhance the visual aspect of a blog.

  1. Add the Ananke theme to the themes directory
1git clone https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke

Note: you can also use a git submodule if you have committed your blog to a Repo i.e.

  1. Update the site configuration (i.e. config.toml) to point to the theme
1echo 'theme="ananke"' >> config.toml

NOTE: You may also want to amend the site title. In which case edit the config.toml to adjust the content as necessary.

Run a local static site

Once all the configuration has been performed its time to generate the static site. Fortunately Hugo enables testing by running a local server

  1. Run hugo to render the intial static site
1hugo server -D -p 8080

A bit more about the above command

  • -D show draft content (i.e posts with true status)
  • -p 8080 run the server on localhost:8080
  1. If you make a change to the blog post (while the server is running) it is automatically rendered in the live blog

Generate a static site

In addition to running a localsite, Hugo can also generate a static site.

  1. Generate a static site
1hugo
  1. The result is a new public folder containing the latest version of the site
 1.
 2├── archetypes
 3├── config.toml
 4├── content
 5├── data
 6├── layouts
 7├── public
 8├── resources
 9├── static
10└── themes

General Configuration

A couple of things to note:

  • You dont have to use git submodule for themes. Not using a submodule simplifies deployment where a clone of the repo is required.
  • You dont have to use signed content. Not using signed content (e.g. css/js) means I have less cache related issues.