Getting started with Hugo

May 15, 2020 5 min

What could be better than writing about the very software that powers this blog. I’m talking about the “world’s fastest framework for building websites” Hugo.

Why Hugo

In search for a solution to power a small blog with little to no required configuration, I was looking into different CMS and site generators. The following criterias had to be met:

static site (my server is a little chicken)
FOSS (it’s just a beautiful word, idk what it means)
easy setup and configuration, please
write content in markdown or any easy markup

When I took a look at Hugo I was immediately intrigued. Hugo is written in Go, and not a JS or PHP framework like most other contenders. But here is where it really shines: It is super easy to install and you get content running within seconds. All that is needed is a single binary that setups a development server or publishes content to the production server.

Getting started

Following steps show its simplicity (see also the hugo quickstart).

1. Install

1
apt install hugo

Check out gohugo.io for more installation instructions if you are not in a Debian environment or want to get the latest version.

2. Create new site

1
hugo new site mynewsite

Congratulations! Your new Hugo site is created in /home/dominique/mynewsite.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.

Skeleton directory structure:

mynewsite/
├── archetypes/
│   └── default.md
├── config.toml
├── content/
├── data/
├── layouts/
├── static/
└── themes/

3. Change into the skeleton directory

1
cd mynewsite

4. Install theme

Go to themes.gohugo.io to choose between many themes. I chose the beautiful Anubis theme that we download into the themes/anubis directory:

1
git clone https://github.com/mitrichius/hugo-theme-anubis themes/anubis

5. Add theme to site configuration `config.toml`

1
vim config.toml

1
2
3
4
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "anubis"

6. Start development server

1
hugo server

Visiting the default development page http://localhost:1313 renders following page:

7. Now we can start adding some content

Leaving the server running will give us live updates of our changes.

Let’s create the content/posts directory and add the file content/posts/hitchhiker.md

1
2
mkdir content/posts
vim content/posts/hitchhiker.md

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
---
title: "The Hitchhiker's Guide to the Galaxy"
author: "Douglas Adams"
date: "1979-10-12"
---

## Chapter One

The house stood on a slight rise just on the edge of the village. It stood on
its own and looked out over a broad spread of West Country farmland. Not a
remarkable house by any means — it was about thirty years old, squattish,
squarish, made of brick, and had four windows set in the front of a size and
proportion which more or less exactly failed to please the eye.

The only person for whom the house was in any way special was Arthur Dent, and
that was only because it happened to be the one he lived in...

When we save the file our webpage automagically updates:

Adding top navigation is as simple as editing the configuration file config.toml

1
vim config.toml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
baseURL = "http://example.org/"
languageCode = "en-us"
title = "My New Hugo Site"
theme = "anubis"

[menu]
  [[menu.main]]
    identifier = "tags"
    name = "Tags"
    url = "/tags/"
    weight = 1

  [[menu.main]]
    identifier = "archive"
    name = "Archive"
    url = "/posts/"
    weight = 2

Thanks to the theme support this will automatically create menu items for tags and posts listings.

Now we originally didn’t add any tags to our blog post, so let’s add following line to the header of content/posts/hitchhiker.md

1
2
3
4
title: "The Hitchhiker's Guide to the Galaxy"
author: "Douglas Adams"
date: "1979-10-12"
tags: ["hitchhiker", "42", "science fiction", "novel"]

And our page updates with a navigation bar, subpages for all tags, a tags overview and an article overview.

Check out the exampleSite/ directory of the Anubis theme to see a small example what can be done.

If this theme is too simplistic for you then the Academic theme as “the website builder for Hugo” is definitely worth checking out.

Deploying

To generate static pages for your hosted website, just run following command with the optional --minify switch to reduce the size of generated files — and therefore generated traffic.

1
hugo --minify

If you manage your site with git you can setup git-hooks to automatically deploy your site on changes.

Apache2

1
2
3
4
5
6
7
8
9
<VirtualHost *:80>
    ServerName localhost
    DocumentRoot /home/dominique/mynewsite/public
    <Location />
        Options FollowSymLinks
        AllowOverride None
        Require all granted
    </Location>
</VirtualHost>

Nginx

1
2
3
4
5
6
7
8
9
server {
    listen 80;
    server_name localhost;

    location / {
        alias /home/dominique/mynewsite/public;
        autoindex on;
    }
}

What’s next?

This article described how to get Hugo running and setup a simple page. In a next step I will cover how to integrate the commenting system remark42 into the site.

technology

La blog