How fitting that the first post on a blog is how to essentially set one up. This is my first time using Hugo, so this post is targeting absolute beginners with experience using Unix.

Install Hugo

The first thing you need to do is install the hugo CLI. I did this via Nix, but you can find the instructions for your platform on their site https://gohugo.io/getting-started/installing/.

Nix:

nix-env -i hugo

What I really liked about hugo is that it is simple to use for just writing plain markdown and builds very quickly compared to other static site generators like Gatsby or Jekyll. This really follows in the tradition of golang, which hugo is written in.

Set up local git repository

Next, you can create a new static site with

hugo new site my-site

This should create a directory called my-site and fill it with a template to get started on your site. Then inside the directory, you can create an interactive preview of your site using hugo server. This hosts a local version of your site on port 1313 on localhost. It was kind enough to bind the address to your localhost too so only you should be able to see it. It should look something like this:

$ hugo server

Start building sites … 

                   | EN  
-------------------+-----
  Pages            | 10  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  1  
  Processed images |  0  
  Aliases          |  2  
  Sitemaps         |  1  
  Cleaned          |  0  

Built in 54 ms
Watching for changes in /Users/kvwu/workspace/kvwu-blog/{archetypes,content,themes}
Watching for config changes in /Users/kvwu/workspace/kvwu-blog/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

Notice how fast it builds! 54ms is quite good. This is really good for a personal blog where I don’t want to waste a lot of time watching the build process run.

You can initialize git at this point in the my-site directory with git init.

The next thing that I did was set up a nice theme. You can find a lot of great themes available at https://themes.gohugo.io/. I just found one that I liked and added it as a submodule of my new site repository.

git submodule add $THEME_URL themes/$THEME_NAME
# For example for my theme
git submodule add https://github.com/vaga/hugo-theme-m10c.git themes/m10c

This copies the repository at the $THEME_URL in the themes directory, and should have added themes/$THEME_NAME to staging. You can take a look at the theme by adding theme = $THEME_NAME to your config.toml and looking at http://localhost:1313/, and if it looks good to you, commit these changes.

git commit -m 'add theme'

I also found it useful to edit some other information in config.toml. I changed the author and params.description to better fit my needs. These changed the values on the sidebar for my theme. I suppose you could play around and find which configurations change your page.

Set up Gitlab remote repository

Gitlab is a site that allows you to host a git repository online. You could also use Github, but I used Gitlab, so my instructions will be for that.

As far as I know, there isn’t a great way to set up a remote repository on Gitlab through CLI, and it’s not easy to describe how to use their website with words. Their instructions on how to do this can be found here https://docs.gitlab.com/ee/user/project/working_with_projects.html#create-a-project.

Once you have set up a remote repository, you can add your local repository to it

git remote add origin [email protected]:username/projectpath.git
git push

Set up Netlify

Netlify is a service that will host your site for you. This particular section suffers from the same problem as the Gitlab one. Netlify does have a cli, but I used their web UI. However, luckily for us, Netlify provides really detailed instructions on their site for how to host your site: https://gohugo.io/hosting-and-deployment/hosting-on-netlify/.

The tutorial, at least at time of writing, shows how to set up using Github but it’s pretty easy to set up with Gitlab as well by just clicking Gitlab instead of Github when prompted.

When prompted to select your repo, select the repo you just created and your master branch. This will create a hook so that whenever you push your master branch, you will deploy a new version of the website.

One issue that I encountered with the compatibility was that my theme required at least hugo 0.55, but Netlify was using 0.54 by default. In this case you can create a netlify.toml file e.g.

[context.production.environment]
HUGO_VERSION = "0.81.0"

to specify your hugo version. I chose 0.81 because that was the version that I had installed, which I think should lead to the most consistent experience. You can find out which version you’re using by running hugo version.