Getting started with Hugo: Beginning

Welcome, this is the first post in my new blog. I found only two reasons for doing self-hosted blog:

1. I can select the engine and formatting instead of getting annoyed with limitations of managed (although free) platforms such as Medium.
2. Controlling blog hosting makes it more resilient compared to external hosting that is driven by business dedcisions over which I have no control.

So, I decided to do an experiment with creating a blog website and in a year (it will be March, 2025) to run a retrospective of the blog hosting and maintenance and decide whether I will continue with the project. Until then I will mirror most of the materials to my blog on Medium.

After finishing with WHY, let’s talk about HOW. There are multiple Blog engines that let you generate content and show it on a website. I spoke with several colleagues and searched on the internet and selected to use Hugo. I am familiar with Hugo. It is simple. It let writing posts using Markdown language. I believe that Markdown is sufficient to format the content in a way I want. If something is missing, Hugo has extensions with rich scripting language. And Hugo has themes so I do not need to deal with Website designing (Good bye “Bootstrap”). Additionally, Hugo has Github action – peaceiris/actions-hugo that can be used to automate CICD pipeline.

First steps

Using Hugo in the local environment is straightforward. It is a single binary. I followed instructions from the site and downloaded and unpacked the tar.gz file (version 0.123.8). Then copied the hugo binary to /usr/bin. Woalla, I have Hugo!

Next step is creating a new website. I created a new folder (I selected an original name blog for it). And then I ran the Hugo “new” command to create the full website layout:

hugo new site

Since Github was my obvious choice for website source management, the next command in the same folder was:

git init

The last thing of the business was to select a look for my blog site a.k.a. theme. I went to themes.gohugo.io. You can search more hugo theme collections on Google. I ended up selecting the Mainroad theme. Do not ask me why. Just liked it. The nice thing about Hugo is that you can change the theme as easily as you install your first one.

There are several ways to install a Hugo theme. I went with the simplest one. I downloaded and copied all the theme’s files to blog/themes/mainroad a.k.a. theme’s folder. Because this theme is hosted on Github, I did some clean up to remove unrelated files from the theme’s folder. I went to delete all files starting with dot (e.g. .gitignore), all markdown files such as CONTRIBUTING.md, README.md, package* files. And I deleted the folder exampleSite that contained a demo website that used the Mainroad theme. Other theme may have other unrelated files. I do not think that keeping these files changes anything. I just prefer to keep file hierarchy tidy.

To run the website locally I used the “hugo serve” command. It allows to open the local version of the website on localhost:1313. However, the website still does not use the theme I downloaded.

I need to change some Hugo configuration first.