Introduction

After graduating from college, I finally decided to start a blog / journal to record my miscellaneous adventures and life stories. I have tried many blog services before, such as WordPress, Blogger, and Tistory (Korean blogging platform), but every blog ended up neglected and abandoned.

This time around, I wanted to build my website instead of relying on the readily available blog platforms. While searching around for static site generators (SSG), I had two candidates: Jekyll and Hugo. Jekyll is an SSG based on Ruby, closely tied with GitHub. Hugo, on the other hand, is written in Go, and I found many first-hand testimonials that Hugo is faster than Jekyll. Although I didn’t expect myself to create much content to need the “fast build speed,” I thought it would be worthwhile to learn an entirely new framework. Thus began my Hugo journeys.

Installation

In order to use Hugo, you must install Hugo on your machine. I have chocolatey on my computer, so I used choco to install Hugo.

choco install hugo-extended -confirm

Note that “hugo-extended” should be installed for the Sass/SCSS support, which is required for some themes.

After that, navigate to a directory of your choice and run:

hugo new site <site name>

Now you’re good to go.

Themes

Browse the Hugo Themes website to find a theme. Each theme has an installation guide on its theme page. In general, the theme package should go under the theme directory of your hugo base directory.

After downloading the theme, copy the config.yaml/toml from the theme directory and move it to the config.yaml/toml of the base hugo directory. Edit the options as you please.

Now what?

Now you see that there are many directories under your hugo base directory. I will go over those with brief explanations.

page

page is mostly used for static single pages. I used it for the “About” section.

post

post is for your blog/article posts.

For new contents, type hugo new post/<new-post>.md. This will create a new .md file named <new-post> under the post directory. Hugo will later render the contents of this markdown file to a static page. Refer to the theme’s sample website directory to get an idea of what should go in the “front matter,” which is the yaml/toml block at the top of the post markdown file.

For example, this website uses the following front matter:

---
title: "How to Hugo"
date: 2020-05-17T20:25:30-05:00
draft: false
---

layouts

layouts directory is used for the templates of your website.

You can also customize the themes by editing the contents of the html files inside the layouts directory. Anything in your base hugo directory will override files within the theme directory. The layouts are a html file templates where you can use Go functions to squeeze in the contents of the markdown files. It was a little intimidating at first, but this feature really opens up a lot for customization.

layouts/partials

partials are basically shortcodes that can be used for rendering small html elements. You can insert partials in your layout files, so that you can achieve a modular design. In my portfolio website, I made a partial called “project-card” that renders html card element from the input data. A template in the layouts directory will then iterate over the yaml data and pass each data entry to this partial to render a bunch of cards.

<div class="project-card">
    <div class="project-line">
        <div class="project-title">
            <b>{{.title}}</b>
        </div>
        <div class="project-when">
            {{.when}}
        </div>
    </div>
    <div class="project-line">
        <div class="project-stack">
            Stack: {{delimit .stack ", "}}

        </div>
        <div class="project-link">
            {{if .link}}
            <a href="{{ .link }}"><i class="fas fa-link"></i></a> {{end}}
        </div>
    </div>
    <div class="project-description">
        {{.description}}
    </div>
</div>

resources

resources is a directory for media resources such as images and videos. I created a subdirectory called images to store my image files. To link the files, you can just use images/<file-name> directly.

data

this website does not have a data directory, but you can create one if you need. You can store a data files in json/yaml/toml formats that could be used elsewhere in your website.

How to test the website

Once you have everything set up, simply run hugo server -D and visit http://localhost:1313.

Note that the -D flag includes content marked as a draft.

How to deploy

After editing your post, run hugo to build your website. It’s as simple as that. The rendered website will be placed under the public directory. Upload the contents of the public directory to a hosting service of your choice, and you are good to go. I have two hugo-generated websites, one hosted on AWS S3/CloudFront, and another hosted on GitHub pages. I will make a separate post on my experience with those two services soon.