Working with Hugo

Last Friday I went live with this updated site and I am no longer having to update Wordpress or a plugin every week which gives me more time to focus on other things. Here is a quick post on how I have been working with hugo covering a quick setup, content writing and deploying changes to a live site.

Getting installed

I already have Go installed as I use it a bunch for all sorts of different projects at work so for me all I had to do was install Hugo, As I tend to swap between my PC running Windows and Ubuntu and my Mac I had to set it up on all 3 environments so that I can write content no matter I am using and push the changes.

Windows

For my Windows install I use the Chocolatey package manager to make life a bit easier, Installing Hugo is then just one line.

choco install hugo -confirm

Mac

On MacOS I went with Brew as I already use it and it is often the first thing I install as I have a handy script I run to automatically set up a new machine and install the software I use.

brew install hugo

Linux

My desktop runs Ubuntu and there is a handy package available, If you are running 18.04 (Bionic) the latest release you will get is 0.40.1 but with a bit of package pinning you can grab 0.52 from 19.04 (Disco)… You could also use a Snap package or install from source.

sudo apt install hugo

You can check to see if Hugo is installed by opening your terminal of choice and running hugo version

Creating a New Site

With Hugo now installed we can create a new website, Hugo has a command you can run which create all of the files and folders you will need to get started.

hugo new site domain.tld

I won’t go over the changes and options needed in config.toml as it change depending on what themes and features you are using so instead let’s look at the folders that you will be mostly using.

Content

Content is the folder which will contain all of your posts and pages, Your structure under here will also determine your URLs so if you put test-file.md file under content/posts/2019/01/ the link to that post would be http://your-domain.tld/posts/2019/01/test-file/ you can change the URL / slug in the post which is what I have been doing (an example of this will be below).

I have found that having the control to have my folders and files with whatever names I want very handy to organise the content I currently have and with the options available to change the URLs I can tweak my structure without worrying about links changing.

Static

Static is a handy file to place any files that you don’t want Hugo to touch so any images, extra css or site verification files, The content put into static can be found by using http://your-domain.tld/your-static-file.extension. I have been putting my images into a folder called images under static to keep things tidy.

Public

Public contains your compiled site and will be what you want to upload to your hosting provider, I like to clear the contents of this folder when I do a new build which may not be needed but it doesn’t seem to add a noticeable amount of time to the build / deploy process.

Writing Content

The big change here from using Wordpress is there is no fancy web interface for adding new content although you could use a Markdown editor if you wanted an easy to use interface or Forestry which aims to make the entire process much easier by putting a layer on top of the Markdown and Git repository to make it more accessible.

I have been using VSCode to write and move my content over and so far all is going well, I run the command below in the terminal and I can check my changes on a local copy of the site. The buildFuture option allows me to see posts which have a date set in the future before they go live.

hugo server --disableFastRender --buildFuture

One of the things I have been missing is the Yoast SEO Plugin which did some handy checks on the page content so having to manually do the same checks takes a few more minutes.

Adding in tags, meta descriptions, changing slugs or setting the URL is all done using options set at the top of the file. For this post I am using the options below which explain themselves. There are more available but at the moment this is covering my needs.

---
author: "Jonathan"
date: 2019-01-11T12:30:00
title: Working with Hugo
url: /posts/working-with-hugo
description: "Working with Hugo is easier than you might think at first, Take a look you might also decide to drop Wordpress or similar."
tags:
  - Hugo
  - How To
---

Deploying Changes

As mentioned at the start of the post I use Windows, MacOS and Linux so I wanted a way to deploy the changes that would work on all 3 systems and while I could just check out the repo on all 3 systems then push the changes and have the web server pull the repo on a schedule and build the site I decided to go with a local script so that I didn’t need to set up a Go environment on the web server.

As 2 out of 3 of the systems has a nice terminal I can work with out of the box and I have WSL installed I use a small shell script which I found on the Hugo website carefully pasted below.

#!/bin/sh
USER=web-server
HOST=joffcom.net
DIR=/var/www/html

rm -rf public/*

hugo && rsync -avz --delete public/ ${USER}@${HOST}:${DIR}

exit 0

Now when using Mac and Linux in VSCode I just need to run ./deploy and on Windows I just run bash ./deploy nice and simples.