Hugo Static Site Generation

Introduction

This personal website was generated using HUGO¹ for the purpose of documenting any experiments and projects I might be working on. It seems only prudent to make the first post on creating the site itself.

HUGO is a static site creation tool which allows Markdown² to be converted into HTML. One can make use of it’s templating engine, many available themes³ and inbuilt functions⁴ to create easy-on-the-eyes webpages in a quick and clean looking way.

Installation (Ubuntu 18.04)

Pick a theme³
Find latest release on GitHub⁵

Install based on URL obtained in step 2.

1
2
3
4


cd /tmp
wget https://github.com/gohugoio/hugo/releases/download/v[].[].[]/hugo_[].[].[]_Linux-64bit.deb
sudo dpkg -i /path/to/deb/file
sudo apt-get install -f

Generate a new site, add desired theme and a first post.

1
2
3
4
5
6
7


# Create a new site
hugo new site blog
cd blog
# grab desired theme
git submodule add https://github.com/jbub/ghostwriter.git themes/ghostwriter
# Create a new post
hugo new posts/initial-post.md

Run. Hugo can serve most pages / functionality by itself. Running the following command with -D flag will start the Hugo webserver rendering all draft versions. Hugo will catch any updates by default, making development quite easy.
```
hugo server [-D|--buildDrafts]
```
Render. To run in any real life setup, the markdown files and templates need to be converted into actual HTML. The following command will create a /public directory in the project directory structure and fill it with all needed static files. Now you can setup your webserver of preference and start serving those files.
```
hugo -v
```

Configuration

The main configuration file can be written in multiple markup languages like TOML and YAML and holds parameters like language encoding, title and menu items, although you can customize these and make this as intricate as you like. This main file lives in the directory root. Inside each static page one can add additional configuration and metadata in the form of a header. The header that was included to generate this very page looks as follows:

---
title: "Hugo Static Site Generation"
date: 2021-01-08T15:02:25+02:00
author: Frank Korving
draft: false
image: "/hugo-logo-wide.svg"
tags: ["coding", "engineering"]
---

There also seem to be LaTeX integrations available which I would like to include in the future⁶ as well as a bunch of options available to include a comment section, however these can be riddled with marketing javascript bloat so I’ll skip on that for now.⁷

Content

Google/Bing/DuckDuckGo yourself to a Markdown Cheatsheet and you’re on 90% your way. A noteworthy thing to me were some of the inbuilt macros that come with Hugo and are called Shortcodes.⁴ This allows for inclusion of nice figures, github gists or code blocks. As an example, one would usually include a code block as follows inside Markdown (where you choose your highlighting flavor at the triple ticks):

# ```bash
# echo "Hello World!"
# ```

echo "Hello World!"

However with Shortcodes one can add things like line numbers. To make this render remove the whitespace between the opening braces: “{ {” -> “{{”.

{ {< highlight bash "linenos=table" >}}
echo "Hello World!"
{ {< /highlight >}}

And to see what that Shortcode gets compiled into:

<div class="highlight"><div class="chroma">
<table class="lntable"><tr><td class="lntd">
<pre tabindex="0" class="chroma"><code><span class="lnt">1
</span></code></pre></td>
<td class="lntd">
<pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="c1"># echo &#34;Hello World!&#34;</span></code></pre></td></tr></table>
</div>
</div>

Ansible, NGINX and Certbot

While one can locally serve the page through the inbuilt hugo webserver, this is only really meant for testing purposes. Some additional steps one can/must/should make:

Certbot: I used the wonderfully easy-to-setup certbot to generate some TLS certificates just to have that nice green button in your address bar.⁸⁹ acme.sh is a great alternative.¹⁰
NGINX: Webserver used to serve this simple site.¹¹ Also shoutout to Qualys SSLLabs¹² + Mozilla¹³ for TLS configuration assistance.
Ansible: Configuration management so I can quickly redeploy this thing somewhere else if necessary. Absolutely unnecessary step but I wanted to brush up on my ansible skills ^_^.¹⁴

Conclusion

This whole thing took me merely a few hours from googling to implementation and that includes scrolling through a bunch of themes to choose which one I liked most. Since I am by no means a front-end developer it felt great to have such a readable, plug-and-play way to generate this site.

Of course I have to say that my use cases are very limited in scope and I have not done any serious comparison with other comparable frameworks like Jekyll.¹⁵ However I have not had to look at a single line of CSS which made my experience awesome enough for a recommendation :D.

tl;dr: Hugo is easy to use, easy on the eyes and saves time to spend on more interesting matters.