Getting started with Hugo

Hello World

Yes, this is my first static website generated with Hugo.

I first got into web design as a kid in 1996 with Geocities (remember Geocities?) before it was aquired by Yahoo. I spent hours manually creating hundreds of static pages involving a lot of copy/pasting.

But hey, my web journey was young and I didn’t know any better.

Later, I discovered the concept of dynamic websites, and for a long time I didn’t really consider static sites to be useful. Everything I created was dyncamic by default (or at least allowed the option). PHP was my go-to server-side language, and I became quite proficient at it.

But what if something generally considered to be dynamic - like a blog - could be static? Wouldn’t that make things easier?

To begin my journey into this bold new world I chose Hugo. First, it seemed capable and simple. Second, it’s written in Google's Go Programming Language (golang), which is something I’ve been wanting to learn more about.

So, what is Hugo?

Here are some quotes from the official Hugo website at the time of writing:

  • Ideal for blogs, docs, portfolios and much more.
  • Sites built with Hugo can be deployed on S3, GitHub Pages, Dropbox or any web host.
  • Hugo is designed for speed and performance.
  • Organize your content however you want with any URL structure.

and so on. Sounds like a great first option to explore the world of static web page generation.

Installation & Setup

The idea is to create the content in Markdown locally, use Hugo to generate the static webpages, then push it to a web host like Amazon S3. This article steps through setting up the local environment. For these steps I’m using Windows 10 64-bit.

Step 1. Install Hugo

Installing Hugo was easy with following the Installing on Windows tutorial found here. Essentially, all that’s required is to download and run an executable.

The basic steps are:

  1. Create a directory structure like C:\Hugo\Sites and C:\Hugo\bin
  2. Download the Windows-64 version of Hugo
  3. Extract the zip into the ..\Hugo\bin directory

The guide also recommends renaming the executable to hugo.exe, which I went ahead and did.

Now the guide also recommends adding ..\Hugo\bin to your PATH variable. I sometimes hesitate to do this with new programs unless forced to, but with Hugo I found it essential for ease of use.

Launch a command prompt and type hugo help to verify everything is working

Step 2. Build your first site

Within the command prompt, type the below (ensuring to substitute mysitename appropriately).

cd C:\Hugo\Sites
hugo new site mysitename

Now check out the contents of C:\Hugo\Sites\mysitename - your new Hugo site is ready to go.

Step 3. Install a theme

As of the time I’m writing this (v0.18.1), Hugo has no default theme. So we may as well go ahead and install one now. I went with the Blackburn theme.

Complete the below steps after generating the site because we need the \mysitename\themes folder to exist.

  1. Download the zip file and extract it into C:\Hugo\Sites\mysitename\themes\.

  2. Copy and paste the example config.toml into C:\Hugo\Sites\mysitename\config.toml. This will define some semantics of the site, as well as the left navigation menu. Later on, you can play around with this file by commenting out or adding new sections to see what happens.

Step 4. Create some content

Hugo provides a Quickstart guide that covers creating a new site and pages.

To create a new page launch the command prompt and type:

cd C:\Hugo\Sites\mysitename

hugo new post/hello-world.md

This will create a file in C:\Hugo\Sites\mysitename\content\post\hello-world.md

We can edit this file in any text editor to enter our content in Markdown (a lightweight markup language).

Step 5. Try it out

We can run the site locally to test it out. In the command prompt run the following:

hugo serve --buildDrafts --theme=blackburn-master

The --buildDrafts flag tells Hugo to include pages with the parameter draft = true

The --theme flag allows us to specify the theme to use.

Open your preferred browser and navigate to http://localhost:1313 and you should see your website.