Setup Hugo Blog

February 22, 2020

Page content

Hugo is a static web site generator. I use Hugo to make this page (see general->impress).

Caution

I wouldn’t recommend this method if you want to upgrade hugo continuously.

Install

TL;DR

If you are Go-lang user, please go next section. Unless, I highly recommend you, who just want to use Hugo features (not Go), to install as follows (official says “Install Hugo from Tarball”).

curl -sSL https://github.com/gohugoio/hugo/releases/download/v0.97.3/hugo_0.97.3_Linux-64bit.tar.gz -o hugo.tar.gz
tar xvfz hugo.tar.gz
sudo cp hugo /usr/local/bin

My environment

macOS 10.15.3
At 2020/02/22

Pre-requirement (install Go)

Hugo is written in Go; therefore, we need to install it first. I installed it with the package installer. This link is an official installation manual.

Notes. In the case of Linux, I install Go usually with tar.gz file because it is easy to understand dependencies. If you don’t intend a big Go project and just want to try snippets, https://play.golang.org is the best way for your purpose!

After running the installer don’t forget to add the path to the shell (zsh in my case).

export PATH=$HOME/go/bin:$PATH

Install Hugo

I used “Fetch from GitHub” method.

Install Hugo (official): https://gohugo.io/getting-started/installing/#fetch-from-github

Here are the commands I executed.

mkdir $HOME/src
cd $HOME/src
git clone https://github.com/gohugoio/hugo.git
cd hugo
go install --tags extended

Make simple homepage

Auto-generate the site directory

The directory name is blog.

hugo new site blog

Manage with Git

cd blog
git init

Make a sample page

hugo new general/imprint.md #

The last command generates general/imprint.md in content directory.

(Optional) Make skelton files not directory to be disappeared

I created several .gitkeep files. Without this command, the created default directory will vanish once you push the hugo project directory to GitHub or any other Git repositories.

touch data/.gitkeep && touch layouts/.gitkeep && touch resources/_gen/assets/.gitkeep && touch resources/_gen/images/.gitkeep && touch static/.gitkeep

Add a theme

Hugo themes make our page “cool.” I use Mainroad because it is simple, widely-used (I believe), and has a lot of features.

Official Mainroad theme page: https://themes.gohugo.io/mainroad/

We should put a theme directory in the themes . With the following command, you can download the theme Mainroad from GitHub repository, which means we can manage our theme in the latest version.

git submodule add https://github.com/Vimux/mainroad.git themes/mainroad

Note: when you pull the repo

If you add the theme like above, you should --recursive option when you git clone your blog repository.

git clone --recursive {your_repo}

After download, enable the config in config.toml.

...
theme = "mainroad"
...

Run a Hugo webpage server in local

You are ready to generate your blog. You can build your blog with the command hugo in blog directory. But before build, I recommend you to use the following command.

hugo server

hugo command generates your blog, and it is stored in docs directory. But when you see the HTML pages in there with browser, the layout is off sometimes. In this case, hugo server will show you a clear preview.

After hugo server, open the browser and check http://localhost:1313 !!

Update Hugo

cd $HOME/src/hugo
git pull
go install --tags extended

28/11/2020: Should I change install method…?

When I upgrade hugo, I

deleted downloaded hugo Git directory, and
re-cloned and re-install.

But there were a pair of issues, like $GOPATH. I think, this method is not maintainable.