My Blog Setup - First Look at Hugo Configuration Setting

On the previous post, I have explained how to bootstrap the blog repository and its CICD and publish it to the public. The site is accessible from https://<user>.gitlab.io/<repo-name>, in case of mine: https://bangau1.gitlab.io/my-blog/.

A bit of disclaimer, that is not my real blog repository. Mine is private :smile:

Hugo Directory and Content Structure

Disclaimer: I only explain the content structure of Hugo, the Hugo Template by Gitlab.

Now, before we take a look at some important configuration in Hugo, let me explain in general how the Hugo content structure

├── config.toml
├── content
│   ├── _index.md
│   ├── page
│   │   └── about.md
│   └── post
│       ├── 2015-01-04-first-post.md
│       ├── 2015-01-15-pirates.md
├── resources
│   └── _gen
│       ├── assets
│       └── images
├── static
│   └── favicon.ico
└── themes
    └── beautifulhugo

config.toml file

This is the Hugo configuration file in toml format that contains all settings about:

• information about the site: Author information and Social Link (e.g: Facebook, Twitter, GitHub, Gitlab, etc)
• the site system and content rendering parameter

You can use another Hugo supported format: yaml and json.

content directory

This is the content location. It consists of 2 subdirectories:

• page
  This is a placeholder where you can put all independent page that doesn't show like the post entry. For example: About Us, Contact Us, and Portfolio Page.
• post
  All content in this folder will appear descendingly by post's published date. This will be your main folder where you put the site's posts.

It also has a special file _index.md. This is for to display a sticky content Post entry. Let say you have a lot of posts and the reader will go through some pagination. This sticky content will be always displayed. It may be useful in some cases: such as Important Announcement to the readers.

resources directory

TBH, I don't know much about this folder other than it is used by Hugo to generate the assets and images after doing some image processing. You can basically ignore this at this time.

static directory

In contrast to resources folder, in static directory you can put pretty much any static files in there. Normally you put Site's icon asset, the avatar, and other assets that you can think of.

themes

Pretty obvious, it's to include the theme for the site. From Gitlab Hugo Template, by default, it uses beautifulhugo theme.

Hugo Important Configurations

Take a look at config.toml file, this is the initial configuration generated by Gitlab Hugo template:

baseurl = "https://bangau1.gitlab.io/my-blog/"
contentdir    = "content"
layoutdir     = "layouts"
publishdir    = "public"
title = "Beautiful Hugo"
canonifyurls  = true

DefaultContentLanguage = "en"
theme = "beautifulhugo"
metaDataFormat = "yaml"
pygmentsUseClasses = true
pygmentCodeFences = true
#disqusShortname = "XXX"
#googleAnalytics = "XXX"

[Params]
  subtitle = "Hugo Blog Template for GitLab Pages"
  logo = "img/avatar-icon.png"
  favicon = "img/favicon.ico"
  dateFormat = "January 2, 2006"
  commit = false
  rss = true
  comments = true
#  gcse = "012345678901234567890:abcdefghijk" # Get your code from google.com/cse. Make sure to go to "Look and Feel" and change Layout to "Full Width" and Theme to "Classic"

#[[Params.bigimg]]
#  src = "img/triangle.jpg"
#  desc = "Triangle"
#[[Params.bigimg]]
#  src = "img/sphere.jpg"
#  desc = "Sphere"
#[[Params.bigimg]]
#  src = "img/hexagon.jpg"
#  desc = "Hexagon"

[Author]
  name = "Some Person"
  email = "youremail@domain.com"
  facebook = "username"
  googleplus = "+username" # or xxxxxxxxxxxxxxxxxxxxx
  gitlab = "username"
  github = "username"
  twitter = "username"
  reddit = "username"
  linkedin = "username"
  xing = "username"
  stackoverflow = "users/XXXXXXX/username"
  snapchat = "username"
  instagram = "username"
  youtube = "user/username" # or channel/channelname
  soundcloud = "username"
  spotify = "username"
  bandcamp = "username"
  itchio = "username"
  keybase = "username"


[[menu.main]]
    name = "Blog"
    url = ""
    weight = 1

[[menu.main]]
    name = "About"
    url = "page/about/"
    weight = 3

[[menu.main]]
    identifier = "samples"
    name = "Samples"
    weight = 2

[[menu.main]]
    parent = "samples"
    name = "Big Image Sample"
    url = "post/2017-03-07-bigimg-sample"
    weight = 1

[[menu.main]]
    parent = "samples"
    name = "Math Sample"
    url = "post/2017-03-05-math-sample"
    weight = 2

[[menu.main]]
    parent = "samples"
    name = "Code Sample"
    url = "post/2016-03-08-code-sample"
    weight = 3

[[menu.main]]
    name = "Tags"
    url = "tags"
    weight = 3

I won't explain all of them, but only the important things to make your blog truly yours (not from template anymore)

baseurl

This must be set correctly so Hugo can render the asset links correctly by using this baseurl information. Please set it to the public domain and path of your site.

title

The title of your blog site.

disquessShortname

This is commented by default. Please uncomment it so that you can use Disqus to provide reader able to comment on your blog post. Go to Disqus Homepage, sign up, retrieve the short name, and put it in config.toml file.

googleAnalytics

Hugo doesn't offer stats view analytics tool out of the box. However, you can use Google Analytics (GA) to gather knowledge about your blog stats view. Put your GA user id there, usually in the format UA-xxxxxxx-xx.

enableemoji

This is not displayed by default in the configuration file. But since emoji in our daily life has become a thing, I think using emoji in the blog would be nice added-value too. Just put enableemoji = true in config.toml.

Params.subtitle

The subtitle under [Param] section is for the subtitle of the blog.

Params.logo and Params.favicon

These settings are important. Put the customized logo and favicon in the static folder and refer it to the configuration.
For example, this is my blog configuration snippet

[Params]
  subtitle = "Movie lover. Engineer. DevOps"
  logo = "avatar.jpg"
  favicon = "avatar.jpg"

And I put the avatar.jpg both for logo and favicon in static folder

blog.agung.io/static
├── avatar.jpg

Params.Author

This is where you put all the information about the blog author and her/his social media link account. If you don't use some of them, you can just remove them from the configuration.

Params.menu.main

This is a special parameter to organize the top bar menu of the blog. Here you can specify multiple menus, name them, put it under the parent menu if you want, and sorted them by the weight (low weight means the most left).
Example for this blog, I only have these 3 menus

[[menu.main]]
    name = "Blog"
    url = ""
    weight = 1

[[menu.main]]
    name = "About"
    url = "page/about/"
    weight = 2

[[menu.main]]
    name = "Tags"
    url = "tags"
    weight = 3

I think I've listed all necessary configuration to make the blog more personalized.

If you think there are other additional configurations that are important, please comment below :smile:

Test in Local

Now to play around with these configurations and contents without having to publish it first, you can test it locally first.

1. Install Hugo binary that you can find the instruction here
2. Go to the blog repository folder, then invoke

hugo serve

That command will build the blog and print information where you can access it locally. Normally it's http://localhost:1313

Pretty simple and fun right?

What's Next

Next post, I am gonna tell you the workflow on creating a new blog post with Hugo. Stay tuned!