Oliver Conzen

Setting up a minimal static website with hugo

Other generators

There is an abundance of static website generators and themes to choose from. The most prominent example is probably Jekyll with a wide variety of themes, configurations, etc. Jekyll is not the right choice for me, since I want to generate the pages with the smallest number of dependencies as possible. Jekyll requires an installation of ruby and is managed by rubys own weird package manager. No thank you.

Then there is Hexo, which has the same problem. Hexo uses Node.js and npm, with which I am familiar atleast, so the problem is not as bad. However, directly after installation the user is greated with warnings courtesy of npm audit. I noped out at this point. It is likely, that the packages work perfectly well for my limited use case. However, some of the audit warnings sound serious and I don’t think that it is worth taking risks when equally complete alternatives exist.

Hexo is still worth mentioning, since it has a pretty large community around it, with many themes and blogs, apparently primarily from Asian users. Also, out of the box it has features like live reload and a build in server for previewing.

Here comes Hugo. Hugo is a single 20 MB binary that the user installs with a package manager of choice or by compiling the source code themself – hahahaha. No matter what option is chosen, Hugo is easy to install and get rid off because of this. Hugo still has all the awesome features that I wanted out of my static site generator of choice and had the benefit of being really easy to set up. So easy in fact that I will run you through it.

Baby steps towards the first page

Start by installing Hugo onto your system. You can find detailed information in the project’s excellent documentation. Here is the page on how to install Hugo. Ideally, the Hugo binary is now in your path. Next you need a place to store your project. From here on out, we will refer to this place as $root. This place is most likely the folder where you store other projects or websites. Fire up a terminal emulator of your choice and change the current directory to be this root folder. In case you forgot:

1
cd $root

Congratulations! You did it! Great job, dude.

Next, think of a fun name for the project you want to create. I called mine blog. What an amazing name. You can either steal this idea or come up with something that is almost as mediocre as mine. Next execute:

1
hugo new site your-project-name

Hugo will now generate a directory with bunch of awesome stuff for you. It will also inform you on what to do next.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
Congratulations! Your new Hugo site is created in $root/your-project-name .

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.

Will do, boss!

Where to go from here

What you have to do next really depends on what you want to do with your page and what you stylistic preferences are. I wanted a very minimal design. That is why I started with simple-hugo-theme by Xzya and made a couple changes to it. I choose the theme, because it is very minimal and thus responsive. After all, it is mostly just text. If you chose a different theme, be sure to follow the themes setup steps.

Next up, you probably want to add content to your page. Hugo has support for different page types, e.g. single pages and blog posts, and ways to aggregate them using e.g. tags. I highly recommend reading the official documentation.

Update

This post was in limbo for over a year now. I finally decided to clean it up and plublish it. If you have any question, please feel free to contact me with the email address at the bottom of the page.