Building a Blog With Hugo (My Experience)

Over time I’ve found myself collecting random thoughts in short writeups on my phone notes, so I decided to cobble them together in a blog to throw online. This lined up pretty well with that regular urge to start a side-project that I know I’ll never finish, so I decided to build a blog with Hugo. This post covers the process of creating the site and the decisions made along the way.

Why Hugo?

After years of working with tools like React, Vue, Tailwind, Vuetify and many many other abstractions, I’ve felt myself slowly drift away from the fundementals of the web. I figured this was a good opportunity to give myself a refresher in the fundementals of HTML & CSS, while providing an opportunity to learn more.

Hugo allows you to build your own theme from the ground up, which allows me to focus on designing how I want while keeping the actual blogging component simple to manage via markdown. Writing in Markdown also allows me to stick with the tools I’m already familiar with (mainly VS Code + Vim).

Being able to build everything into static files allows you to easily deploy to nearly any host/CDN on the planet. It makes the site easy to deploy, quick to navigate and cheap (effectively free) to maintain. I don’t see myself needing any dynamic components that require a server, so this is a great option for me.

Creating a New Hugo Site and New Theme

After creating a new repo on Github and opening it in my terminal, I ran the following commands.

1
2
3
4
5
6
7
8

# Create a new site in current directory
hugo new site . --force

# Create a new theme called "vogelaar" 
hugo new theme vogelaar

# Start the hugo server in dev mode
hugo server -D

I should probably have come up with a more creative name for my theme, but my surname seems unique enough. I was surprised to see some content included in the new theme by default, I’m not sure why you’d include posts inside your theme itself. If anyone knows why you would do this, please let me know. After deleting the content directory I’m left with the following structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

vogelaar/
├── archetypes/
├── assets/
├── data/
├── i18n/
├── layouts/
├── static/
├── LICENSE
├── README.md
├── hugo.toml
└── theme.toml

Based on other themes I could find, I then cut this down further to the following list of essential directories, to keep things simple. I also merged the contents of hugo.toml to the equivalent file in the site itself. A lot of these files are not necessary if you don’t intend to publish your theme for others to use.

1
2
3
4
5

vogelaar/
├── assets/
├── layouts/
├── README.md
└── theme.toml

I appreciate that the CSS and JS are kept separately in assets, while the developer maintains complete control of how they’re injected into the layouts.

Designing the Theme

I’ve never been much of a designer, but I obviously wanted to build something that I would enjoy looking at. It also had to be easy on the eyes and quick to skim through without having to focus too hard. Luckily for me, something I use every day which meets these requirements is my colour scheme in my editor, Atom One Dark.

While I’m not sure I wish to use this as a design/colour scheme long term, it’s a good starting point to escape the procrastination of obesessing over unimportant design details for hours before building anything. All the colours have been grouped in the main CSS file in variables so that I can change them easily when I inevitably need to satisfy that itch. themes/vogelaar/assets/css/main.css:

1
2
3
4
5
6
7
8
9

:root {
  --text-color: #abb2bf;
  --bg-color: #282c34;
  --heading-color: #e06c75;
  --italic-color:#98c379;
  --link-color: #61afef;
  --code-color: #c678dd;
  --time-color: #e5c07b;
}

For the font, I decided to go with Recursive, more specifically the monospaced, casual variant of this font. I came across it while reading Sunaku’s excellent post about his Moergo Glove80 keyboard layout, I use this keyboard on and off and enjoy using a modified version of his symbol layer. The font is pleasant to read and is well-suited to large amounts of text.

Where possible I’ve tried to keep the CSS as simple as possible. It’s very easy to get caught up in creating detailed, pixel-perfect styling, but in many cases the default user agent stylesheet of the user’s browser covers most of the essentials. I’ve tried as much as possible to avoid excessive use of divs, sticking to more descriptive elements that are better for accessibility and SEO.

All this comes together for an initial theme that’s easy to read and matches my personal tastes.

Improving the other pages

Just by focussing on the theming on the Single Post template, most of the site actually looks pretty close to being done. I spent a bit more time going through the different pages and making some adjustments and improvements.

While I’m happy for the main page to just stay as a list of blogs for now, there are a few things that needed cleaning up from the default theme template:

• The blog contents were just dumped one on top of each other with no semantic separation. Each blog preview got it’s own section tag.
• I added a date on each of the post previews for users to determine how relevant a post is.
• The site title was a h1 tag by default, which would result in multiple h1 tags on most article pages. I’ve updated it so this is only the case on the main page, which does not have it’s own title.

I also added an About page with a bit of info about me. You can read that here.

Technical Improvements

I also made a number of small technical improvements to make the site feel a bit more snappy, these include:

• Self-hosting the fonts instead of loading via Google Fonts
• Adding width/height attributes to the default image renderer to prevent layout shifting
• Adding loading=lazy to the default image renderer to delay image loading until the user gets close to that image

This is my updated image renderer in themes/vogelaar/layouts/_default/_markup/render-image.html:

1
2
3
4
5
6
7

{{- $image := .Page.Resources.GetMatch (printf "%s" (.Destination | safeURL)) -}}
<img
    src="{{ .Destination | safeURL }}" alt="{{ .Text }}"
    {{ with $image }}
    width="{{ $image.Width }}" height="{{ $image.Height }}"
    loading="lazy"
    {{ end }} />

Wrapping Up

At this point the site is ready to go live! I have a separate post detailing how to deploy the site to Cloudflare Pages. I very surprised at just how quickly I was able to put together a fast, easy to manage and pleasant to read site using just Hugo with no external dependencies. This took me just a few hours to complete making it one of the only personal projects I’ve actually finished. I hope this has been useful to anyone else looking to set up a site themselves.

Want to Leave a Comment?